markdown-it-docutils [IN-DEVELOPMENT]
A markdown-it plugin for implementing docutils style roles (inline extension point) and directives (block extension point). The package also vendors a default CSS, with light/dark mode adaptive colors and overridable CSS Variables.
See https://executablebooks.github.io/markdown-it-docutils/ for a demonstration!
Usage
As a Node module:
import MarkdownIt from "markdown-it"
import docutilsPlugin from "markdown-it-docutils"
const text = MarkdownIt().use(docutilsPlugin).render("*a*")In the browser:
<!DOCTYPE html>
<html>
<head>
<title>Example Page</title>
<script src="https://cdn.jsdelivr.net/npm/markdown-it@12/dist/markdown-it.min.js"></script>
<script src="https://unpkg.com/markdown-it-docutils"></script>
<link
rel="stylesheet"
type="text/css"
media="screen"
href="https://unpkg.com/markdown-it-docutils/dist/css/style.min.css"
/>
</head>
<body>
<div id="demo"></div>
<script>
const text = window
.markdownit()
.use(window.markdownitDocutils.default)
.render("*a*")
document.getElementById("demo").innerHTML = text
</script>
</body>
</html>Supported roles (inline extensions)
Roles are any token in the token, within an inline token's children with the role type:
Token.meta = { name }should contain the name of the roleToken.contentshould contain the content of the role
By default (see parseRoles option), roles are parsed according to the MyST syntax: {name}`content`.
All roles have a fallback renderer, but the the following are specifically handled:
- HTML:
sub: Subscript (alternativelysubscript)sup: Superscript (alternativelysuperscript)abbr: Abbreviation (alternativelyabbreviation)
- Referencing
eq: Reference labeled equationsref: Reference any labeled or named block, showing titlenumref: Numbered reference for any labeled or named block (useFigure %s <my_label>)
- Basic:
raw
Supported directives (block extensions)
Directives are any token in the token stream with the directive type:
Token.infoshould contain the name of the directiveToken.meta = { arg: "" }should contain the argument (first line) of the directiveToken.contentshould contain the body of the directiveToken.mapshould be set
By default (see replaceFences option), all fences with a language delimited in braces will be converted to directive tokens, e.g.
```{name} argument
:option: value
content
```
All directives have a fallback renderer, but the the following are specifically handled:
- Admonitions:
admonitionnoteattentioncautiondangererrorimportanthintnoteseealsotipwarning
- Image:
imagefigure
- Code:
codecode-blockcode-cell
- Tables:
list-table
- Other:
math
CSS Styling
markdown-it-docutils distributes with a default dist/css/style.min.css styling, primarily adapted from the furo sphinx theme.
The CSS makes extensive use of CSS Variables.
These can be overridden by the user and are used for stylizing nearly all elements of the documentation.
The colors are in light mode by default, switching to the dark mode when requested by the user’s browser (through prefers-color-scheme: dark). See the prefers-color-scheme documentation for details.
As a consequence of this design, the dark mode inherits the variable definitions from the light mode, only overriding specific values to adapt the theme. While the mechanism for switching between light/dark mode is not configurable, the exact CSS variable definitions used in this process can be configured with CSS Variables.
Design Notes
TODO improve this:
- Parsing all directives/roles to "generic" directive/role tokens first (with fallback renderer), then "run" the directives/roles
- this separates the logic for parsing these syntaxes, from the logic for interpreting their content, i.e. the syntax for a directive/role can in theory be anything, as long as it can be converted to the necessary token
Development
Features
- TypeScript
- Code Formatting (prettier)
- Code Linting (eslint)
- Testing and coverage (jest)
- Continuous Integration (GitHub Actions)
- Bundled as both UMD and ESM (rollup)
- Upload as NPM package and unpkg CDN
- Simple demonstration website (GitHub Pages)
Getting Started
- Create a GitHub repository from the template.
- Replace package details in the following files:
package.jsonLICENSEREADME.mdrollup.config.js
- Install the
node_moduledependencies:npm installornpm ci(see Install a project with a clean slate). - Run code formatting;
npm run format, and linting:npm run lint:fix. - Run the unit tests;
npm test, or with coverage;npm test -- --coverage.
Now you can start to adapt the code in src/index.ts for your plugin, starting with the markdown-it development recommendations.
Modify the test in tests/fixtures.spec.ts, to load your plugin, then the "fixtures" in tests/fixtures, to provide a set of potential Markdown inputs and expected HTML outputs.
On commits/PRs to the main branch, the GH actions will trigger, running the linting, unit tests, and build tests.
Additionally setup and uncomment the codecov action in .github/workflows/ci.yml, to provide automated CI coverage.
Finally, you can update the version of your package, e.g.: npm version patch -m "🚀 RELEASE: v%s", push to GitHub; git push --follow-tags, build; npm run build, and publish; npm publish.
Finally, you can adapt the HTML document in docs/, to load both markdown-it and the plugin (from unpkg), then render text from an input area.
This can be deployed by GitHub Pages.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent