Configuring Remarkdown
There are three ways to customize Remarkdown:
Pick optional styles in HTML
Combine the remarkdown class and optional style classes to enable optional styles:
<section class="remarkdown h1-line ul-star">
<h1>Using remarkdown.css</h1>
…
</section>
Or with the remarkdown.attr.css variant, use the data-remarkdown attribute:
<section data-remarkdown="h1-line ul-star">
<h1>Using remarkdown.attr.css</h1>
…
</section>
If you don’t fancy Remarkdown’s default styles, you can use Remarkdown-zero instead (remarkdown-zero.css or remarkdown-zero.attr.css), and declare all the styles you want explicitly.
<section class="
remarkdown
hn-prefix h1-line
ul-plus ol-alpha
a-bracket em-star
…
">
<h1>Using remarkdown-zero.css</h1>
…
</section>
Note: most styles named *-reset are still enabled by default in the Remarkdown-zero variants. If you want a build of Remarkdown without those, you will need to create a custom Sass build.
Override CSS variables and styles
Remarkdown defines a few CSS variables for basic typography and spacing:
--rmd-base-font: ui-monospace, monospace;
--rmd-code-font: inherit;
--rmd-line-height: 1.5;
--rmd-ul-indent: 3ch;
--rmd-ol-indent: 3ch;
On top of that, all the characters used to render a Markdown-like syntax are exposed as variables:
--rmd-hn-prefix: "#";
--rmd-h1-line: "====================";
--rmd-h2-line: "--------------------";
--rmd-ul-dash: "-";
--rmd-ul-star: "*";
--rmd-ul-plus: "+";
--rmd-ol-mark: ".";
--rmd-pre-ticks: "```";
--rmd-pre-tilde: "~~~";
--rmd-pre-tilde-line: "~~~~~~~~~~~~~~~~~~~~";
--rmd-quote-mark: ">\a>\a>\a>\a>\a>\a>\a>\a>\a>\a";
--rmd-quote-rtl: "<\a<\a<\a<\a<\a<\a<\a<\a<\a<\a";
--rmd-hr-stars: "* * * *";
--rmd-hr-dashes: "-------";
--rmd-table-vline: "|\a|\a|\a|\a|\a|\a|\a|\a|\a|\a";
--rmd-table-hline: "--------------------";
You can override any of these to tweak Remarkdown’s appeareance. For example:
<section class="remarkdown" style="
--rmd-base-font: Consolas, Menlo, ui-monospace, monospace;
--rmd-ul-indent: 4ch;
--rmd-ol-indent: 4ch;
--rmd-h2-line: '////////////////////';
--rmd-ul-dash: '➡️';
--rmd-hr-stars: '🌟 🌟 🌟';
">
<!-- Your content here -->
</section>
Note that vertical margins, colors and other cosmetic styles are not handled by these variables. If you want to tweak colors and more, you will need to write your own style overrides. Here are a few examples:
Example 1: make markers pop
Style ::before and ::after pseudo-elements to add a touch of color and visual separation:
@scope (.remarkdown) to (.no-remarkdown) {
::before,
::after {
color: hsl(190 44% 36%);
text-shadow: 1px 2px hsl(190 66% 75%);
opacity: 0.75;
}
}
Example 2: make titles big again
Remarkdown sets the font-size of headings to 100% to better achieve that plain text look. But if you want big titles anyway, it’s easy:
@scope (.remarkdown) to (.no-remarkdown) {
h1 { font-size: 1.5rem; font-weight: bold; }
h2 { font-size: 1.2rem; }
}
(Alternatively, if you’re compiling your own build, you can remove the hn-reset style from $default-styles.)
Beware of selector specificity
Depending on the variant of Remarkdown used, its selectors can have low or somewhat high selector specificity. Some of the highest specificity selectors look like :scope.ol-alpha ol > li (specificity: 0,2,2) and [data-remarkdown~=ol-alpha] ol > li (specificity: 0,1,2).
To override those, you could match those selectors exactly, while making sure that your styles are included after the Remarkdown styles.
But a simpler fix, if you’re familiar with CSS cascade layers, is to assign all Remarkdown styles to a layer with lower precedence:
@layer rmd, rmd-overrides;
@import "remarkdown.css/dist/remarkdown.attr.css" layer(rmd);
@layer rmd-overrides {
/* Has priority over styles in the "rmd" layer,
despite the low-specificity selector */
h1 { margin-block: 0; }
}
Build a custom Sass stylesheet
Remarkdown is written in Sass, published to npm, and can be imported as a Sass library to generate a custom Remarkdown variant with your own config.
This section assumes that you are using Node.js and the sass package — via its CLI or a bundler like Vite.
Minimal setup with npm
Install Remarkdown and Sass using npm (or any alternative package manager):
npm install sass remarkdown.css
You should then be able to import remarkdown.css in any .scss stylesheet. For example, let’s call it my-remarkdown.scss:
@use "pkg:remarkdown.css" as rmd;
@include rmd.header("Remarkdown %v (custom build)");
@include rmd.styles();
Now compile this Sass stylesheet with:
npx sass my-remarkdown.scss --pkg-importer=node
Sass “Can't find stylesheet to import @use "pkg:remarkdown.css"”?
Using a package specifier like pkg:remarkdown.css requires the --pkg-importer=node option on the command line, or the proper configuration when using Sass programatically or with a bundler.
If your bundler or setup doesn’t support Sass’s pkg: specifiers, you can fall back to one of the following options:
// 1. npm package name only (works with most bundlers)
@use "remarkdown.css" as rmd;
// 2. relative path to package dir in node_modules
@use "../node_modules/remarkdown.css" as rmd;
// 3. relative path to the package’s `lib/_index.scss` entrypoint:
@use "../node_modules/remarkdown.css/lib" as rmd;
This should generate a my-remarkdown.css stylesheet that is very similar to the pre-built remarkdown.css. Which is maybe not that interesting. Thankfully, we can use the rmd.config() mixin to customize the output.
@use "pkg:remarkdown.css" as rmd;
// Always include `rmd.config` first, or `rmd.header`
// and `rmd.styles` will use the default config
@include rmd.config(
$preset: "zero",
$css-vars: "--%s",
$base-font: ("Comic Sans Mono", "monospace"),
$ol-mark: ")",
);
@include rmd.header("Remarkdown %v (custom build)");
@include rmd.styles();
Next we’ll discuss a few options that can be set with the rmd.config() mixin. For a full list, refer to the source code in lib/_defaults.scss.
$preset
This option lets you pick between the "default" and "zero" sets of Remarkdown styles. Defaults to "default".
@include rmd.config(
$preset: "default" // or "zero"
);
The main difference between both presets is that the zero preset has only a few reset styles listed as $default-styles.
Check out the source for both presets for more information:
default: lib/_defaults.scsszero: lib/_defaults-zero.scss
$default-styles and $optional-styles
The $default-styles option selects which Remarkdown styles are included in the CSS output using $default-selector. It accepts a list of style names.
The $optional-styles option selects which styles are included in the CSS output using $option-selector. It accepts a list of style names, or a boolean value (true or false):
$optional-styles: truemeans that all styles not listed in$default-styleswill be emitted as optional styles in the CSS output.$optional-styles: falsemeans that no optional styles will be emitted in the CSS output.$optional-styles: (a, b, c)means that only the styles with the namesa,bandcwill be emitted as optional styles in the CSS output.
Here are a few possible combinations:
// Example 1:
// - custom default styles
// - treat other styles as options
@include rmd.config(
$default-styles: (hn-reset, hn-prefix, h1-line, h2-line, ul-star, ol-alpha, strong-reset, strong-underscore, hr-dash, hr-center),
$optional-styles: true,
);
// Example 2:
// - no default styles at all!
// - everything is an optional style
@include rmd.config(
$default-styles: (),
$optional-styles: true,
);
// Example 3:
// - keep default $default-styles
// - do not output optional styles
@include rmd.config(
$optional-styles: false
);
$base-selector, $default-selector and $option-selector
These options determine what Remarkdown’s CSS selectors look like in the CSS output.
$base-selector: for CSS variables and basic text styles;$default-selector: for styles listed in$default-styles;$option-selector: for styles listed in$optional-styles.
Note that in $option-selector, the substring %s is required and will be replaced by the optional style’s name.
The default configuration is:
$base-selector: ".remarkdown";
$default-selector: ".remarkdown";
$option-selector: ".remarkdown.%s";
With the default selectors above, the CSS output would look like (abridged version):
/* $base-selector: ".remarkdown" */
.remarkdown {
--rmd-base-font: ui-monospace, monospace;
--rmd-line-height: 1.5;
/* … more css vars */
font-family: var(--rmd-base-font);
line-height: var(--rmd-line-height);
}
/* $default-selector: ".remarkdown" */
.remarkdown em::before,
.remarkdown em::after {
content: "*"/"";
}
/* $option-selector: ".remarkdown.%s" */
.remarkdown.em-underscore em::before,
.remarkdown.em-underscore em::after {
content: "_"/"";
}
As another example, the main remarkdown.css stylesheet uses somewhat different selectors in order to use native CSS scoping with @scope:
@include rmd.config(
$base-selector: ":scope",
$default-selector: "",
$option-selector: ":scope.%s"
);
@scope (.remarkdown) to (.no-remarkdown) {
@include rmd.styles();
}
This results in CSS output looking like:
@scope (.remarkdown) to (.no-remarkdown) {
/* $base-selector: ":scope" */
:scope {
--rmd-base-font: ui-monospace, monospace;
--rmd-line-height: 1.5;
/* … more css vars */
font-family: var(--rmd-base-font);
line-height: var(--rmd-line-height);
}
/* $default-selector: "" */
em::before,
em::after {
content: "*"/"";
}
/* $option-selector: ":scope.%s" */
:scope.em-underscore em::before,
:scope.em-underscore em::after {
content: "_"/"";
}
}
For more examples, check out how the default stylesheets define their selectors here: build/*.scss.
More options…
See lib/_defaults.scss for the full list of Sass options that can be customized with rmd.config().