Minimal Markdown to HTML converter implemented using Goldmark with support for GitHub-Flavored Markdown, with additional extensions for developing technical course content.
Supports
- Mermaid diagrams.
- Tables.
- Strikethroughs.
- Automatic linking of URLs.
- Raw "pass-through" HTML.
- Client-side highlighting of source code blocks with "copy to clipboard" functionality.
- Notices (admonitions, like "tip", "warning", "note", and others.)
It also has a few additional Markdown extensions for rendering commands and program output, as well as highlighting text.
This tool can also emit a minimal starter stylesheet. Custom CSS is not supported with this tool. If you need it, append the output of this program after a <style> definition containing your CSS.
The tool is designed to be used with other CLI tools or as part of a build chain.
Generated code blocks are not marked up for syntax highlighting. Use Highlight.js on the client to syntax highlight code. This tool can generate the appropriate Highlight.js JavaScript code as well as buttons to copy the code snippets.
Download the binary for your OS and place it on your PATH.
This tool accepts Markdown text via Standard Input and prints the converted HTML to Standard Output:
The most basic usage would be like the following example, where lesson.md is the input, and lesson.html is the output:
lessonmd < lesson.md > lesson.htmlIf you prefer, you can pipe the output of cat:
cat lesson.md | lessonmd > lesson.htmlYou can also use a Bash herestring:
lessonmd <<< "Hello world" > lesson.htmlIf you're on macOS, you can send the output directly to the clipboard using the built-in pbcopy command:
lessonmd < lesson.md | pbcopyIf you need to convert multiple files, you can do this in Bash:
for f in *.md; do lessonmd < "${f}" > "${f%.md}.html"; doneThe HTML output will be wrapped in a <div> tag with the class item, which will make styling easier. Use the -no-wrap flag to generate unwrapped output, or use the -c flag to specify a different class name.
YAML frontmatter is skipped by default. To preserve it, add the -include-frontmatter flag which renders the front matter as an HTML table at the top of the document.
Use the -include-stylesheet flag to generate a <style> block at the top of the document with some basic CSS styling you can build on.
lessonmd -include-stylesheet < lesson.md > lesson.htmlYou can also emit the basic CSS file using the -print-stylesheet flag:
lessonmd -print-stylesheet > style.cssYou can add the -c flag to specify a different class.
lessonmd -print-stylesheet -c lesson-item > style.cssUse -h to see the options:
-c string
The class name for outer div (defaults to 'item'. (default "item")
-h Show this help message.
-include-frontmatter
Include YAML frontmatter as a table. Defaults to false - frontmatter is omitted.
-include-highlight-js
Include script tags to include Highlight.js client-side libraries from CDN and add copy-to-clipboard functionality.
-include-mermaid-js
Include script tags for client-side Mermaid rendering.
-include-stylesheet
Include CSS in a <style> tag in the output.
-no-wrap
Do not wrap output with outer <div> tag.
-print-highlight-js
Print the JavaScript code for client-side syntax and clipboard support.
-print-mermaid-js
Print the JavaScript code for Mermaid support.
-print-stylesheet -c
Print the CSS file to standard output. Provide optional parent class. (defaults to 'item' - use -c to change.)
-use-mermaid-svg-renderer
Use embedded SVG for Mermaid instead of client-side JavaScript.
-v Prints current app version.
To generate a single page with CSS, Highlight.js, and Mermaid support, use the following command:
lessonmd -include-highlight-js \
-include-mermaid-js \
-include-stylesheet \
-c "lesson_item" \
< examples/lesson.md > lesson.htmlThe following features are available:
Tables, automatic linking, and strikethroughs are available.
Wrap words or phrases with == to trigger highlighting.
Example:
This is ==fancy==.
Marking up code fences with the command language type will transform them to use the bash language, but annotate them so you can style them with CSS differently.
Example:
```command
make clean
```
Marking up code fences with the output language will transform them into a <div> with the Output label and the output. This will let you use CSS to differentiate them from regular code snippets, commands, or file listings.
Example:
```output
This is program output
```
You can now define a region that expands and collapses. These are good for questions and answers:
[details What's the best Markdown tool?
lessonmd is the best.
]
You can also make them open by default:
[details open These details are open
And everyone can see them.
]
Add Mermaid diagrams using the mermaid language type:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
By default, you'll only be able to process Mermaid diagrams when the page is rendered and you've added Mermaid's client-side processing. Use the -include-mermaid-js flag to append a <script> block that loads Mermaid, or add it yourself.
To process Mermaid diagrams server-side, install the Mermaid CLI:
npm install -g @mermaid-js/mermaid-cliThen use the -use-mermaid-svg-renderer flag.
This embeds SVGs into the Markdown, so there's no need for client-side JavaScript.
This tool generates code blocks compatible with Highlight.js. Add HighlightJS to your system and the code blocks will highlight automatically.
Use the -include-highlight-js flag to add a <script> block to the bottom of the output that will load Highlight.js from a CDN and add "Copy" buttons so readers can copy code to the clipboard.
Alternatively, run with the -print-highlight-js option to emit just the script so you can add it to your LMS or platform.
Sometimes you'll want to have notices or callouts in your documents, often called "admonitions."
:::warning This is a warning
Use this to warn people of something that may go wrong.
:::
This generates a block with a title and some contents:
<div class="notice warning">
<div class="notice-heading">This is a warning</div>
<div class="notice-body">
<p>Use this to warn people of something that may go wrong.</p>
</div>
</div>
You can use tip, info, note, caution, or warning. You can place links or code blocks within this as well.
The included stylesheet has basic styling for these as well.
This is built using Goldmark which supports Common Mark. Goldmark is a good fit because you can add extensions to the AST or the rendering functions separately. This means adding extensions will be easier.
Here's a map of what the files are in the project:
.
├── Makefile <- Builds all of the executables
├── README.md <- this file
├── bin
│ └── lessonmd.go <- The CLI interface
├── converter.go <- The main Markdown to HTML converter
├── converter_test.go <- Test cases
├── examples
│ └── lesson.md <- An example doc
├── extensions <- Custom GoldMark extensions
│ ├── commandblocks <- Parser and HTML renderer for command blocks
│ ├── inlinehighlight <- Parser and HTML renderer for inline highlighting
│ ├── notices <- Parser and HTML renderer for notices
│ └── outputblocks <- Parser and HTML renderer for output blocks
├── go.mod
└── go.sum
There's a ton to do.
- Math support - MathJax support for Goldmark is spotty and requires client-side work as well.
- Support highlighting within code blocks
- Create code block labels
What's not going to happen:
- custom CSS: You can do this using
catto append your own stylesheet. - Full HTML page generation: Again, use
cator another tool to wrap this output with your own template. - Conversion to other formats: Use Pandoc to convert the HTML.
- Add support for details (expandable sections)
- Add admonitions:
tip,note,info,caution, andwarningand appropriate CSS. - Add link color to CSS.
- Add table header CSS to make it stand out.
- Add zebra striping to tables.
- If the document contains YAML front matter, it's ignored by default.
- The
-include-frontmatterflag renders front matter as an HTML table.
- Initial release