markdown-to-html

Markdown renderer aiming at providing :

• A static site generator (converting .md to .html)
• A live server (serving rendered .md files)

Features

• Markdown files are rendered using the powerfull Marked library.
• Marked is extended with :
  • Table of content generation in markdown files ([[toc]] from pandoc)
  • The support of custom heading links (# This is the title {#custom-id})
  • The hability to rename .md to .html for relative links for static site generation.
• A basic layout system based on handlebars with some built-in layouts :
  • default to generate classic pages.
  • remarkjs to generate slideshows.
• front-matter allows to use YAML metadata to :
  • Overwrite page title (default is file path)
  • Overwrite page lang (default is "en")
• Partial HTML/JS views can be injected in the layout to bypass markdown limitation for some pages.

Usage

Install

npm install -g @mborne/markdown-to-html
# check version
markdown-to-html --version
# show help
markdown-to-html --help
# markdown-to-html [serve|convert|check] --help

Generate static website

markdown-to-html convert samples/01-default-layout /tmp/output

Serve markdown file

# with the default layout
markdown-to-html serve samples/01-default-layout
# with a custom layout
markdown-to-html serve samples/02-remarkjs --layout remarkjs

Check markdown files

To check links between markdown files :

markdown-to-html check samples/01-default-layout
# to include HTTP test for remote URLs
markdown-to-html check samples/01-default-layout --check-external-links

Credits

• marked provides the markdown parser.
• handlebars provides the template engine.
• commander allows CLI options handling.
• shelljs allows to list files, copy directory, etc.
• front-matter allows YAML metadata parsing
• marked-custom-heading-id provided the solution to support custom heading id.
• express provides the server mode.

It is inspired from :

• mixu/markdown-styles
• hads

Samples

| Example | Source | Layout | | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Classic example | samples/01-default-layout/index.md | layout/default/page.html | | RemarkJS slideshow | samples/02-remarkjs/index.md | layout/remarkjs/page.html | | GitHub pages generated mixing both | mborne/cours-patron-conception | see build.js |

License

MIT

Alternatives

See jamstack.org - Site Generators :

• Jellyll
• MkDocs, Material for MkDocs,...
• Docsify
• Docusaurus
• HADS - Hey it's Another Documentation Server!
• ...

Docs

• DEV - Debug with Visual Studio Code