Customizing ReMarkdown

There are three ways to customize ReMarkdown: picking available styles in HTML, adding your own CSS styles, and building ReMarkdown with Sass and custom settings.

Picking styles in HTML

You can activate the available styles by declaring them in your HTML, as classes or attribute values:

<div class="remarkdown h1-underline ul-star">
  <p>Using remarkdown.css</p>
</div>

ReMarkdown Zero

If you don’t want to use ReMarkdown’s default styles, you can use the remarkdown-zero.css stylesheet instead, and declare all the styles you want explicitly.

<div class="remarkdown hn-reset hn-hash h1-underline ul-star a-bracket pre-tick quote-gt ...">
  <p>Using remarkdown.css</p>
</div>

Using attributes instead of classes

ReMarkdown comes with an alternative remarkdown.attr.css stylesheet which uses the data-remarkdown attribute for styling, instead of classes:

<head>
  <link rel="stylesheet" href="https://unpkg.com/remarkdown.css/dist/remarkdown.attr.css">
  <!-- or https://unpkg.com/remarkdown.css/dist/remarkdown-zero.attr.css -->
<body data-remarkdown="h1-underline a-bracket ul-plus ol-alpha">
  ...
</body>

Add your own CSS

I strive to make ReMarkdown free of cosmetic choices. For instance, the layout and colors of this demo are not handled by remarkdown.css. So you probably want to add a few CSS styles of your own to make the end result prettier. Here are a few suggestions.

Make markers pop out

.remarkdown ::before,
.remarkdown ::after {
  color: rgba(255, 0, 0, .5);
}

Specify you own fonts

ReMarkdown tells browsers to use their default monospace font, but you can always specify your own, as I did here:

/* remarkdown.css must be declared BEFORE this */

.remarkdown {
  font-family: Menlo, Monaco, "DejaVu Sans Mono",
    Consolas, monospace;
}
.remarkdown pre {
  font-family: Courier, "Courier New", monospace;
}

In this example I’m using two different monospace font-stacks, one without serifs (Menlo etc.) and one with slab serifs (Courier etc.), to differentiate between ordinary text and code blocks.

You could also use a font that is not monospace. A variable-width font whose design is not too tight could give interesting results.

Make titles big again

ReMarkdown sets the font-size of headings to 1em to better achieve that plain text look (since plain text editors and file formats use the same font size for all text). But if you want big titles anyway, it’s easy:

.remarkdown h1 { font-size: 1.5em; }
.remarkdown h2 { font-size: 1.2em; }

Alternatively, if you’re compiling your own build, there is an option to disallow ReMarkdown from setting any font style.

Beware of selector specificity

Most ReMarkdown selectors have a specificity of 0,0,1,1 or in some cases 0,0,1,2. If your own selectors have similar weight, make sure you declare your own styles after remarkdown.css. Alternatively you can make use of id selectors or of the double-class trick:

.remarkdown h1 {
  /* Selector has a specificity of 0,0,1,1 */
}
.myTitle.myTitle {
  /* Selector matches and has a specificity of 0,0,2,0 */
}

Learn more about selector specificity.

Build a custom stylesheet with Sass

You can recompile ReMarkdown using Sass, and there are a number of options (Sass variables) that you can use to alter the CSS output of your custom build.

Things you will need:

Once you’ve downloaded and extracted the ReMarkdown source, modify the src/remardown-custom.scss stylesheets, changing or adding $rmd-* variables to change your build’s configuration. See src/_options.scss for a detailed list of options.

To compile, use a terminal (Terminal on macOS, cmd.exe or Git Bash on Windows, etc.), navigate to the root of the extracted folder (probably called remarkdown-main), and run these commands:

npm install
npm run build

Note: if you already have your own Node-and-Sass build chain in place, you can install ReMarkdown with npm install remarkdown.css and import the main mixins with @import "node_modules/remarkdown.css/src/_imports.scss";.

Example: changing the default styles

You can use the $rmd-defaults variable to change the styles that should be applied by default (i.e. when you use the remarkdown class without any explicit style).

$rmd-defaults:
  hn-reset hn-hash h1-underline h2-underline
  ul-star ol-decimal
  em-underscore strong-underscore
  hr-hyphen hr-center;

You will need to list all the styles you want to see apply by default. That can be a fairly long list (as above). For instance, if I omit both em-star and em-underscore, EM elements won’t have any visible marker (unless we explicitly set one of those styles in the HTML code).

Example: only output default styles

By setting the $rmd-output-all-styles option to false, ReMarkdown will only output those styles that are listed in $rmd-defaults. This can be useful if you want to pick a set of default styles, don’t intend to ever use the alternative styles, and want to make a smaller CSS file.

Currently the default build with all styles included is close to 8 KB, while the same defaults with no alternative styles included is down to 4 KB.