hackmd-to-html-cli
v2.0.0
Published
A node.js CLI tool for converting HackMD markdown to HTML.
Maintainers
ksw2000Readme
hackmd-to-html-cli
Not only is this a CLI tool, but it is also an importable package for converting standard Markdown and even HackMD-supported Markdown into HTML.
- Example of input markdown: ./example/index.md
- Example of output html: https://ksw2000.github.io/hackmd-to-html-cli/
- Example of output html in dark mode: https://ksw2000.github.io/hackmd-to-html-cli/index.dark.html
- Example of converting in web: https://ksw2000.github.io/hackmd-to-html-cli/webjs.html
Install
# CLI
npm install -g hackmd-to-html-cli
# Package
npm install hackmd-to-html-cliCLI
$ hmd2html --help
hmd2html --help
Usage: index [options]
Options:
-v, --version output the current version
-i, --input <files_or_urls...> the path/url of input markdown files
-d, --dest <dir> the path of output directory (filename is generated automatically) (default: ./output)
-o, --output <files...> the path of output file (ignored if the flag -d is set) (default: "")
-l, --layout <html_file> specify the layout file (default: "")
-b, --hardBreak use hard break instead of soft break
-k, --dark use the dark mode layout (activate only if the -l option is not set)
-h, --help display help for commandConvert
# convert files
$ hmd2html -i file1.md file2.md file3.md
# allow wildcard input
$ hmd2html -i dir/*.md
# allow url input
$ hmd2html -i https://github.com/ksw2000/hackmd-to-html-cli/blob/main/example/index.md
# set output folder
$ hmd2html -i file1.md -d ./my_output
# set the filename of output
$ hmd2html -i file1.md -o file1.html
$ hmd2html -i file1.md file2.md -o file1.html file2.html
# use default darkmode layout
$ hmd2html -i file1.md -k
# use custom layout
$ hmd2html -i hello.md -l ./myLayout.htmlLayouts
We provide the two default layouts. Please see layouts here: https://github.com/ksw2000/hackmd-to-html-cli/blob/main/layouts/
{{main}}renders main content of markdown.{{lang}}renders lang property if there are yaml metadata aboutlangin markdown file. e.g.lang="zh-TW"{{dir}}renders dir property if there are yaml metadata aboutdirin markdown file. e.g.dir="ltr"{{meta}}renders meta tag if there are yaml metadata abouttitle,description,robotsorimage. e.g.<meta name="robots" content="noindex">
Example:
<!DOCTYPE html>
<html {{lang}} {{dir}}>
<head>
{{metas}}
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
<meta charset="utf-8">
<body>
{{main}}
</body>
</html>There are some features rendered by other dependencies. Thus, in our default layout, we include those dependencies.
Example
CommonJS
const { Converter } = require('hackmd-to-html-cli')
const converter = new Converter();
const res = converter.render("# hello");
console.log(res.main);ES Module
import { Converter } from "hackmd-to-html-cli"
const converter = new Converter();
const res = converter.render("# hello");
console.log(res.main);Web
const converter = new window.hmd2html.Converter();
const res = converter.render("# hello");
console.log(res.main);Support
hmd2html: our tool (the latest)
HackMD Default Converter: The default markdown to html converter provided by HackMD, i.e., download HTML file on HackMD.
HackMD fully supports syntax: features
| Features | hmd2html | HackMDDefault Converter |
|---------------------------------|:--:|:--:|
| ToC | ✅ | ✅ |
| Emoji | ✅ | ✅ |
| ToDo list | ✅ | ✅ |
| Code block | ✅ | ✅ |
| - Show line number or not | ✅ | ❌ |
| - Specify the start line number | ✅ | ❌ |
| - Continue line number | ✅ | ❌ |
| Blockquote | ✅ | ✅ |
| - specify your name | ✅ | ✅ |
| - specify time | ✅ | ✅ |
| - color | ✅ | ✅ |
| Render CSV as table | ✅ | ✅ |
| MathJax | ✅ | ✅ |
| Sequence diagrams | ✅ | ❌ |
| Flow charts | ✅ | ❌ |
| Graphviz | ✅ | ❌ |
| Mermaid | ✅ | ❌ |
| Abc | ✅ | ❌ |
| PlantUML | ✅ | ✅ |
| Vega-Lite | ✅ | ❌ |
| Fretboard | ✅ | ❌ |
| Alert Area | ✅ | ✅ |
| Detail | ✅ | ✅ |
| Spoiler container | ✅ | ✅ |
| Headers h1-h6 | ✅ | ✅ |
| Horizontal line --- *** | ✅ | ✅ |
| Bold **b** __b__ | ✅ | ✅ |
| Italic *i* _i_ | ✅ | ✅ |
| Deleted text ~~del~~ | ✅ | ✅ |
| Superscript ^sup^ | ✅ | ✅ |
| Subscript ~sub~ | ✅ | ✅ |
| Inserted text ++ins++ | ✅ | ✅ |
| Marked text ==mark== | ✅ | ✅ |
| Ruby case | ✅ | ✅ |
| Typographicreplacements | ✅ | ✅ |
| Blockquotes | ✅ | ✅ |
| List | ✅ | ✅ |
| Tables | ✅ | ✅ |
| Links | ✅ | ✅ |
| Link with title | ✅ | ✅ |
| Autoconverted link | ✅ | ✅ |
| Image | ✅ | ✅ |
| - normal | ✅ | ✅ |
| - with title | ✅ | ✅ |
| - given size | ✅ | ✅ |
| Footnotes | ✅ | ✅ |
| Definition list | ✅ | ✅ |
| Abbreviations | ✅ | ✅ |
Support Externals
| Features | hmd2html | HackMDDefault Converter| |-------------|:---------:|:---------:| | Youtube | ✅ | ✅ | | Vimeo | ✅ | ❌ | | Gist | ✅ | ✅ | | SlideShare | ❌ | ❌ | | Speakerdeck | ✅ | ✅ | | PDF | ✅ | ✅ | | Figma | ✅ | ✅ |
Support YAML Metadata
| Features | hmd2html | Implementation |
|---------------|:---------:|:-------:|
| title | ✅ | <title></title><meta name="twitter:title"><meta property="og:title">|
| description | ✅ | <meta name="description"><meta name="twitter:description"><meta property="og:description"> |
| robots | ✅ | <meta name="robots"> |
| lang | ✅ | <html lang=""> |
| dir | ✅ | <html dir=""> |
| image | ✅ | <meta property="og:image"><meta name="twitter:image:src"> |
| others | ✅ | Hide the metadata by html comment |
HackMD sets the lang tag and dir tag at the beginning of <body>. hmd2html sets the the lang tag and dir tag at <html> when using default layout.
Development
npm run lintto check the format of source code.npm run exampleruns example for this package, which generates result from./exampleand places them in./output.npm testruns unit test files whose filenames end with.spec.ts
Contributing
Contributions to hackmd-to-html-cli are welcome and highly appreciated. Please run lint npm run lint and test npm run test before pull requesting.