diff --git a/README.md b/README.md
index cd7e1cc..35ab854 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,77 @@
# Remarkdown
-Remarkdown styles HTML to look like plain Markdown text.
+Remarkdown makes HTML look like plain [Markdown][] text.
-- [online demo and docs][docs]
-- [npm: remarkdown.css][npm]
+- Npm: [remarkdown.css](https://www.npmjs.com/package/remarkdown.css)
+- Documentation:
+ - [Using Remarkdown](https://fvsch.github.io/remarkdown/)
+ - [Remarkdown styles](https://fvsch.github.io/remarkdown/styles)
+ - [Configuring Remarkdown](https://fvsch.github.io/remarkdown/config)
-Markdown is [a plain-text syntax by John Gruber][markdown]. Some styles are inspired by [PHP Markdown Extra][md-extra] and [GitHub Flavored Markdown][md-gfm].
+## Usage with a CDN
-## Documentation
+Add a link to the `dist/remarkdown.css` stylesheet and `class="remarkdown"` on a container wrapping all the text you want to style:
-- [Using Remarkdown][docs]
-- [Available styles][styles]
-- [Customizing Remarkdown][customize]
+```html
+
+
+
+ Using Remarkdown
+
+
+
+
Hello World
+
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 `
`s and asterisks for bullets.
-[npm]: https://www.npmjs.com/package/remarkdown.css
-[docs]: https://fvsch.github.io/remarkdown/
-[styles]: https://fvsch.github.io/remarkdown/styles.html
-[customize]: https://fvsch.github.io/remarkdown/customize.html
-[markdown]: https://daringfireball.net/projects/markdown/
-[md-extra]: https://michelf.ca/projects/php-markdown/extra/
-[md-gfm]: https://github.github.com/gfm/
+The main `dist/remarkdown.css` stylesheet exists in a few variants, which tweak what CSS selectors look like and what styles are enabled by default:
+
+- [remarkdown.css](): normal defaults, `.remarkdown` class.
+- [remarkdown.scope.css](https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css): normal defaults, `.remarkdown` class using [CSS `@scope`][css-scope].
+-
+
+## Usage with npm
+
+```sh
+npm install remarkdown.css
+```
+
+When using a Bundler like [Vite][], you should be able to import pre-built stylesheets from the package’s `dist` directory in your own CSS:
+
+```css
+@import "remarkdown.css/dist/remarkdown.css";
+/* or "remarkdown.css/dist/remarkdown-zero.attr.css", etc. */
+```
+
+Beyond the pre-built stylesheets, Remarkdown is a [Sass][] library, and can be imported with `@use` then configured with the `config()` mixin:
+
+```scss
+@use "pkg:remarkdown.css" as rmd;
+
+// Configure a custom Remarkdown build
+@include rmd.config($line-height: 1.75);
+
+// Generate styles
+@include rmd.header();
+@include rmd.styles();
+```
+
+See the [`preset` directory](https://github.com/fvsch/remarkdown/tree/main/preset) for some examples that modify the Remarkdown selectors, and [`lib/config/_defaults.scss`](https://github.com/fvsch/remarkdown/tree/main/lib/config/_defaults.scss) for all available configuration options.
+
+
+
+[Markdown]: https://daringfireball.net/projects/markdown/
+[Sass]: https://sass-lang.com/
+[Vite]: https://vite.dev/
+[css-scope]: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@scope
+
+[remarkdown.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
+[remarkdown.attr.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
+[remarkdown.scope.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
+[remarkdown.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
+[remarkdown.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
+[remarkdown.css]: https://cdn.jsdelivr.net/npm/remarkdown.css@4/dist/remarkdown.css
diff --git a/dist/remarkdown-zero.attr.css b/dist/remarkdown-zero.attr.css
index 85c9a33..651278d 100644
--- a/dist/remarkdown-zero.attr.css
+++ b/dist/remarkdown-zero.attr.css
@@ -30,23 +30,23 @@
font-family: var(--rmd-code-font);
}
-[data-remarkdown~="a-bracket"] a {
+[data-remarkdown~="a-bracket"] :any-link {
text-decoration-inset: 1ch;
}
-[data-remarkdown~="a-bracket"] a::before {
+[data-remarkdown~="a-bracket"] :any-link::before {
content: "["/"";
}
-[data-remarkdown~="a-bracket"] a::after {
+[data-remarkdown~="a-bracket"] :any-link::after {
content: "]"/"";
}
-[data-remarkdown~="a-showurl"] a {
+[data-remarkdown~="a-showurl"] :any-link {
text-decoration-inset: 0;
}
-[data-remarkdown~="a-showurl"] a[href]::before {
+[data-remarkdown~="a-showurl"] :any-link::before {
content: "["/"";
}
-[data-remarkdown~="a-showurl"] a[href]::after {
+[data-remarkdown~="a-showurl"] :any-link::after {
content: "](" attr(href) ")"/"";
word-break: break-all;
}
diff --git a/dist/remarkdown-zero.css b/dist/remarkdown-zero.css
index d0ace11..8d3548f 100644
--- a/dist/remarkdown-zero.css
+++ b/dist/remarkdown-zero.css
@@ -29,22 +29,22 @@
:is(pre, code, kbd, samp) {
font-family: var(--rmd-code-font);
}
- :scope.a-bracket a {
+ :scope.a-bracket :any-link {
text-decoration-inset: 1ch;
}
- :scope.a-bracket a::before {
+ :scope.a-bracket :any-link::before {
content: "["/"";
}
- :scope.a-bracket a::after {
+ :scope.a-bracket :any-link::after {
content: "]"/"";
}
- :scope.a-showurl a {
+ :scope.a-showurl :any-link {
text-decoration-inset: 0;
}
- :scope.a-showurl a[href]::before {
+ :scope.a-showurl :any-link::before {
content: "["/"";
}
- :scope.a-showurl a[href]::after {
+ :scope.a-showurl :any-link::after {
content: "](" attr(href) ")"/"";
word-break: break-all;
}
diff --git a/dist/remarkdown.attr.css b/dist/remarkdown.attr.css
index 95a94c0..594cc8c 100644
--- a/dist/remarkdown.attr.css
+++ b/dist/remarkdown.attr.css
@@ -30,23 +30,23 @@
font-family: var(--rmd-code-font);
}
-[data-remarkdown] a {
+[data-remarkdown] :any-link {
text-decoration-inset: 1ch;
}
-[data-remarkdown] a::before {
+[data-remarkdown] :any-link::before {
content: "["/"";
}
-[data-remarkdown] a::after {
+[data-remarkdown] :any-link::after {
content: "]"/"";
}
-[data-remarkdown~="a-showurl"] a {
+[data-remarkdown~="a-showurl"] :any-link {
text-decoration-inset: 0;
}
-[data-remarkdown~="a-showurl"] a[href]::before {
+[data-remarkdown~="a-showurl"] :any-link::before {
content: "["/"";
}
-[data-remarkdown~="a-showurl"] a[href]::after {
+[data-remarkdown~="a-showurl"] :any-link::after {
content: "](" attr(href) ")"/"";
word-break: break-all;
}
diff --git a/dist/remarkdown.css b/dist/remarkdown.css
index e2faf6d..4e50f6a 100644
--- a/dist/remarkdown.css
+++ b/dist/remarkdown.css
@@ -29,22 +29,22 @@
:is(pre, code, kbd, samp) {
font-family: var(--rmd-code-font);
}
- a {
+ :any-link {
text-decoration-inset: 1ch;
}
- a::before {
+ :any-link::before {
content: "["/"";
}
- a::after {
+ :any-link::after {
content: "]"/"";
}
- :scope.a-showurl a {
+ :scope.a-showurl :any-link {
text-decoration-inset: 0;
}
- :scope.a-showurl a[href]::before {
+ :scope.a-showurl :any-link::before {
content: "["/"";
}
- :scope.a-showurl a[href]::after {
+ :scope.a-showurl :any-link::after {
content: "](" attr(href) ")"/"";
word-break: break-all;
}
diff --git a/docs/404.html b/docs/404.html
new file mode 100644
index 0000000..c680260
--- /dev/null
+++ b/docs/404.html
@@ -0,0 +1,37 @@
+
+
+
+
+ Remarkdown — Page not found
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+ 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 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:
+
+ (Alternatively, if you’re compiling your own build, you can remove the hn-reset style from $defaults.)
+
+
+
+ Beware of selector specificity
+
+
+
+ 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 afterremarkdown.css:
+
+ 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; }
+
+
+
+ Build a custom stylesheet with Sass
+
+
+
+ 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();
+
+
+ Example: custom selectors
+
+
+
+ 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:
+
+ 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:
+
+ 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).
+
+ 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:
+
+ 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.
-
-
-
- Picking styles in HTML
-
-
-
- You can activate the available styles by declaring them in your HTML, as classes or attribute values:
-
- 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.
-
- 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.
-
- 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:
-
- Alternatively, if you’re compiling your own build, you can remove the hn-reset style from $default-styles.
-
-
-
- Beware of selector specificity
-
-
-
- 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 afterremarkdown.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}
-
-
-
- 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.
-
- 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).
-
- 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.
-
- 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 simply made it because I could.
- Using Remarkdown
+ Usage with a CDN
- 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:
+ 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.
+
+
- Make it your own
+ Usage with npm
- Remarkdown is broken down into a list of styles, and the default remarkdown.css uses a dozen of them by default.
+ Remarkdown is published on npm as 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";
+
+
- You can choose additional variants by adding option names as classes along the remarkdown class. For example:
+ 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.header();
+@include rmd.styles();
+
- Take a look at the customize page for different ways to disable, enable or override styles, change the defaults, change how selectors look, etc.
+ Using it with Sass lets you customize the output further, especially when using the `rmd.config()` mixin. See “Build a custom stylesheet with Sass” for details.
+
+
+
+ Remarkdown variants
+
+
+
+ The pre-built Remarkdown stylesheet comes in a few variants, which change:
+ what default styles are enabled; how optional styles are declared in HTML.
+
+ As far as I’m aware, when I created Remarkdown v1 in 2011, it was the first published implementation of this strange idea of styling HTML like Markdown.
+
+
+
+ Other implementations include Peter Coles’ Markdown.css, and many developer homepages which do some Markdown-ish styling of headings and a few other elements.
+
+ 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.