markdown-it-myst-extras
v0.3.0
Published
Additional markdown-it plugins required for the MyST specification.
Downloads
10,604
Readme
Markdown-It Plugin Template
Additional markdown-it plugins required for the MyST specification.
Usage
As a Node module:
import MarkdownIt from "markdown-it"
import { mystBlockPlugin, colonFencePlugin } from "markdown-it-myst-extras"
const text = MarkdownIt().use(mystBlockPlugin).render("+++")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-myst-extras"></script>
</head>
<body>
<div id="demo"></div>
<script>
const text = window
.markdownit()
.use(window.markdownitMystExtra.mystBlockPlugin)
.render("+++")
document.getElementById("demo").innerHTML = text
</script>
</body>
</html>Development
Features
- TypeScript
- Code Formatting (prettier)
- Code Linting (eslint)
- Testing and coverage (vitest)
- 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;
≈, 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.
Design choices
Why is markdown-it only in devDependencies?
From the markdown-it development recommendations:
Plugins should not require the
markdown-itpackage as a dependency inpackage.json.
Note, for typing, we import this package with import type, to ensure the imports are not present in the compiled JavaScript.
Why Vitest?
There are a number of JavaScript unit testing frameworks (see this comparison, jest is easy to setup/use, flexible, and well used in large projects however does not currently have native support for ESM. vitest was chosen for out-of-the box compatibility with jest, however, it is both more performant and is currently easier to integrate with ESM/TypeScript packages.
Why Rollup?
The three main bundlers are; Webpack, Rollup and Parcel, with the functionality gap between all of these bundlers narrowing over the years.
Essentially, Rollup provides a middle ground between features and complexity, and is good for bundling libraries (it is what markdown-it itself uses).
See for example: