Configuring Remarkdown

There are three ways to customize Remarkdown:

  1. Pick optional styles in HTML
  2. Override CSS variables and styles
  3. Build a custom Sass stylesheet

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-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):

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.

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().