+ Page not found +
+ ++ Nothing to see here. +
+ +A paragraph.
+ + +``` +There are a few [alternate styles](https://fvsch.github.io/remarkdown/styles) you can pick from. For example, `class="remarkdown h1-line ul-star"` enables underlined `+ Nothing to see here. +
+ ++ There are three ways to customize Remarkdown: +
+ + + +
+ Enable optional styles by combining the remarkdown class and the optional style classes:
+
<div class="remarkdown h1-line ul-star">
+ <h1>Using remarkdown.css</h1>
+ …
+</div>
+ With the remarkdown.attr.css variant, use the data-remarkdown attribute instead:
+
<div data-remarkdown="h1-line ul-star">
+ <h1>Using remarkdown.attr.css</h1>
+ …
+</div>+ If you don’t want to use Remarkdown’s default styles, you can use the remarkdown-zero.css stylesheet instead (or remarkdown-zero.attr.css), and declare all the styles you want explicitly. +
+ +<div class="remarkdown hn-prefix h1-line ul-plus ol-alpha a-bracket pre-tick quote-mark …">
+ <h1>Using remarkdown-zero.css</h1>
+ …
+</div>+ Remarkdown defines a few CSS variables: +
+ +.remarkdown {
+ --rmd-font: ui-monospace, monospace;
+ --rmd-code-font: inherit;
+ --rmd-line-height: 1.5;
+ --rmd-hn-prefix: "#";
+ --rmd-h1-line: "====================";
+ --rmd-h2-line: "--------------------";
+ --rmd-hr-stars: "* * * *";
+ --rmd-hr-dashes: "-------";
+ --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-table-vline: "|\a|\a|\a|\a|\a|\a|\a|\a|\a|\a";
+ --rmd-table-hline: "--------------------";
+}
+ Use these variables to tweak Remarkdown’s font-family, or the characters used in syntax markers.
+
.remarkdown {
+ --rmd-font: Consolas, Menlo, ui-monospace, monospace;
+ --rmd-h2-line: "~~~~~~~~~~~~~~~~~~~~";
+ --rmd-hr-stars: "*_* *_* *_*";
+}+ Note that colors and other cosmetic styles are not handled by these CSS variables. If you want to tweak colors and more, you will need to write your own style overrides. Here are a few examples. +
+ +.remarkdown {
+ ::before,
+ ::after {
+ color: hsl(190 44% 36%);
+ text-shadow: 1px 2px hsl(190 66% 75%);
+ opacity: 0.75;
+ }
+}
+ Remarkdown sets the font-size of headings to 100% to better achieve that plain text look (since most 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.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 $defaults.)
+
+ Most Remarkdown styles have a selector 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:
+
@import "remarkdown.css/dist/remarkdown.css";
+/* Includes this selector (specificity 0,0,1,1):
+.remarkdown h1 { margin-block: 1.5lh 1lh; } */
+
+/* Your style overrides (same specificity): */
+.remarkdown h1 { margin-block: 0; }
++ Alternatively, you can use CSS Layers to put all Remarkdown styles in a cascade layer with lower precedence: +
+ +@import "remarkdown.css/dist/remarkdown.css" layer(remarkdown);
+/* Includes this selector (specificity 0,0,1,1):
+.remarkdown h1 { margin-block: 1.5lh 1lh; } */
+
+/* Your unlayered styles have priority,
+despite the lower specificity (0,0,0,1): */
+h1 { margin-block: 0; }
++ 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 part assumes that you are using Node.js and a toolchain that supports Sass, whether that’s npm and the sass package directly, or a bundler like Vite. +
+ ++ Install Remarkdown and Sass using npm (or pnpm or a similar package manager): +
+ +npm install sass remarkdown.css
+ Then you should be able to import remarkdown.css in any .scss stylesheet:
+
@import "pkg:remarkdown.css" as rmd;
+@include rmd.header();
+@include rmd.styles();
+ If the remarkdown.css package is installed but Sass cannot find pkg:remarkdown.css, you may need to configure Sass to resolve pkg: specifiers. Or you can fall back to relative imports instead:
+
@import "./path/to/node_modules/remarkdown.css" as rmd;
+@include rmd.header();
+@include rmd.styles();
+ Remarkdown selectors can be configured with the config() mixin and the $root-selector and $option-selector variables. The default build of Remarkdown uses this configuration:
+
@import "pkg:remarkdown.css" as rmd;
+
+@include rmd.config(
+ $root-selector: ".remarkdown",
+ $option-selector: ".remarkdown.%s"
+);
+
+@include rmd.header();
+@include rmd.styles();
+ Note that in $option-selector, the substring %s will be replaced by the optional style’s name, so that .remarkdown.%s becomes, for example, .remarkdown.h1-line.
+
+ Here is a somewhat contrived example that uses CSS nesting and data-* attributes:
+
@import "pkg:remarkdown.css" as rmd;
+
+@include rmd.config(
+ $root-selector: "&",
+ $option-selector: "&[data-%s]"
+);
+
+@include rmd.header();
+
+[data-remarkdown] {
+ @include rmd.styles();
+}
+ Use the $defaults variable to change the styles that should be applied by default (i.e. styles that will be defined using the $root-selector instead of the $option-selector).
+
@import "pkg:remarkdown.css" as rmd;
+
+@include rmd.config(
+ $defaults: (
+ hn-reset,
+ hn-prefix,
+ h1-line,
+ h2-line,
+ ul-star,
+ ol-alpha,
+ strong-reset,
+ strong-underscore,
+ hr-dash,
+ hr-center
+ )
+);
+
+@include rmd.header();
+@include rmd.styles();
+ 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 markers.
+
+ All styles not listed in $defaults will still be part of the CSS output, but they will use an optional style selector, and so will need enabling in HTML:
+
<div class="remarkdown em-reset em-star">
+ <p>Hello <em>world</em>!</p>
+</div>
+ If you customize the default Remarkdown styles with $defaults, you may not need the remaining styles in the CSS output at all. This is where the $options variable comes in.
+
+ You can explicitly list all styles that should be +
+ +
+ 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. +
+ +- 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. -
- -- You can activate the available styles by declaring them in your HTML, as classes or attribute values: -
- -<div class="remarkdown h1-line ul-star">
- <p>Using remarkdown.css</p>
-</div>- 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-prefix h1-line ul-star a-bracket pre-tick quote-mark …">
- <p>Using remarkdown.css</p>
-</div>
- 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://cdn.jsdelivr.net/npm/remarkdown.css/dist/remarkdown.attr.css">
- <!-- or https://cdn.jsdelivr.net/npm/remarkdown.css/dist/remarkdown-zero.attr.css -->
-<body data-remarkdown="h1-line a-bracket ul-plus ol-alpha">
- …
-</body>- 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. -
- -.remarkdown ::before,
-.remarkdown ::after {
- color: hsl(0 100% 100% / 0.5);
-}
- Remarkdown tells browsers to use their default monospace font, but you can always specify your own, as I did here:
-
.remarkdown {
- font-family: Menlo, DejaVu Sans Mono, Consolas, 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. -
- -
- 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, you can remove the hn-reset style from $default-styles.
-
- Most Remarkdown styles have a selector 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:
-
@import "remarkdown.css/dist/remarkdown.css";
-/* Includes this selector (specificity 0,0,1,1):
-.remarkdown h1 {margin-block: 1.5lh 1lh} */
-
-/* Your style overrides (same specificity): */
-.remarkdown h1 {margin-block: 0}
-- Alternatively, you can use CSS Layers to put all Remarkdown styles in a cascade layer with lower precedence: -
- -@import "remarkdown.css/dist/remarkdown.css" layer(remarkdown);
-/* Includes this selector (specificity 0,0,1,1):
-.remarkdown h1 {margin-block: 1.5lh 1lh} */
-
-/* Your unlayered styles have priority,
-despite the lower specificity (0,0,0,1): */
-h1 {margin-block: 0}
-- 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";.
-
- 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-prefix h1-line h2-line
- ul-star ol-decimal
- em-underscore strong-underscore
- hr-dash 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).
-
- 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. -
- -
- The text you’re reading right now is not plain text, but semantic HTML styled like Markdown text. Right-click and inspect this page to get a feel for how it works.
+ This is a <p> element. That heading above is a real <h1>. Normal semantic HTML, styled to look like plain text.
+
+ That’s Remarkdown in a nutshell: a stylesheet that styles HTML to look like Markdown text. I’m not sure it’s useful, I’ve rarely used it myself; I just made it because I could.
- It’s as simple as downloading remarkdown.css, and adding the remarkdown class to a container:
+ You can use Remarkdown with a CDN like jsDelivr (recommended) or unpkg. When using the main remarkdown.css stylesheet, you will need to add class="remarkdown" on a container wrapping all the text you want to style, like this:
<!doctype html>
<html lang="en">
<head>
<title>Using Remarkdown</title>
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/remarkdown.css/dist/remarkdown.css">
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css">
</head>
-<body class="remarkdown">
+<body class="remarkdown">
<h1>Hello World</h1>
<p>A paragraph.</p>
</body>
</html>
+ There are a few alternate styles you can pick from. For example, class="remarkdown h1-line ul-star" enables underlined <h1>s and asterisks for bullets.
+
- Remarkdown is broken down into a list of styles, and the default remarkdown.css uses a dozen of them by default.
+ Remarkdown is published as a npm package named remarkdown.css. If you’re working in a project using npm (or pnpm or yarn, etc.) and maybe a code bundler like Vite, you should be able to install Remarkdown like so:
+
npm install remarkdown.css
+ Then in your JavaScript modules or CSS files, import one of the compiled stylesheets in the package’s dist folder:
+
// In a JS module processed by a bundler
+import "remarkdown.css/dist/remarkdown.css";/* Or in a CSS file processed by a bundler */
+@import "remarkdown.css/dist/remarkdown.css";
+
+ The remarkdown.css package is also a Sass library, which can be used in Sass modules (.scss files):
+
@use "pkg:remarkdown.css" as rmd;
+@include rmd.config();
+@include rmd.header();
+@include rmd.styles();
++ Using it with Sass lets you customize the output further, especially when using the `config()` mixin. See “Build a custom stylesheet with Sass” for details. +
+ ++ The pre-built Remarkdown stylesheet comes in a few variants, which change: + what default styles are enabled; how optional styles are declared in HTML. +
+ +| Stylesheet | +Defaults | +Selectors | +
|---|---|---|
| remarkdown.css | +Normal | +Classes | +
| remarkdown.attr.css | +Normal | +data-remarkdown attribute |
+
| remarkdown.scope.css | +Normal | +Classes with CSS @scope |
+
| remarkdown-zero.css | +Resets only | +Classes | +
| remarkdown.attr.css | +Normal | +data-remarkdown attribute |
+
| remarkdown.scope.css | +Normal | +Classes with CSS @scope |
+
+ Remarkdown is broken down into a list of styles, and the default remarkdown.css uses a dozen of them by default.
@@ -63,7 +154,7 @@
- Take a look at the customize page for different ways to disable, enable or override styles, change the defaults, change how selectors look, etc. + Take a look at the config page for different ways to disable, enable or override styles, change the defaults, change how selectors look, etc.
+ Here are all the styles provided by Remarkdown. The “default” ones are enabled in the remarkdown.css stylesheet.
+
- All styles that are listed as “Default” here will be active when using the default remarkdown.css build.
- No need to specify class="remarkdown style-name" for those.
- On the other hand, if you want to either disable them or include them in a custom build, it’s helpful to know the style’s name and what it does.
+ You can also use remarkdown-zero.css which has no default styles, and enable styles with HTML classes. And for more control, you can use Sass to make a custom build with your prefered default styles.
| Option name | +Style name | Default | Description |
|---|