Skip to content

Latest commit

 

History

History
116 lines (83 loc) · 4.9 KB

README.md

File metadata and controls

116 lines (83 loc) · 4.9 KB
Raw

Markdown-It Plugin Template

ci-badge npm-badge

A template for creating a markdown-it plugin.

See https://executablebooks.github.io/markdown-it-plugin-template/ for a demonstration!

Usage

As a Node module:

import MarkdownIt from "markdown-it"
import examplePlugin from "markdown-it-plugin-template"

const text = MarkdownIt().use(examplePlugin).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-plugin-template"></script>
    </head>
    <body>
        <div id="demo"></div>
        <script>
            const text = window.markdownit().use(window.markdownitExample).render("*a*");
            document.getElementById("demo").innerHTML = text
        </script>
    </body>
</html>

Development

Features

Getting Started

  1. Create a GitHub repository from the template.
  2. Replace package details in the following files:
    • package.json
    • LICENSE
    • README.md
    • rollup.config.js
  3. Install the node_module dependencies: npm install or npm ci (see Install a project with a clean slate).
  4. Run code formatting; npm run format, and linting: npm run lint:fix.
  5. 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 master 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-it package as a dependency in package.json.

Note, for typing, we import this package with import type, to ensure the imports are not present in the compiled JavaScript.

Why Jest?

There are a number of JavaScript unit testing frameworks (see this comparison, but jest was chosen because of it is easy to setup/use, flexible, and well used in large projects.

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: