Hackmd-to-html-cli NPM

hackmd-to-html-cli

npm.io npm.io npm.io

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

Install

# CLI
npm install -g hackmd-to-html-cli

# Package
npm install hackmd-to-html-cli

CLI

$ 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 command

Convert

# 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.html

Package (beta)

// for TypeScript
// import { Converter } from 'hackmd-to-html-cli'
const { Converter } = require('hackmd-to-html-cli')
const template = `{{main}}`
const hardBreak = true
const converter = new Converter(template, hardBreak)
const md = `
# title
hello world
`
console.log(converter.convert(md))

output

<h1 id="title" tabindex="-1">title</h1>
<p>hello world</p>

Some features

// get default layout
converter.defaultLayout()

// get metadata after converting
converter.getMetadata()

Layout

See default layout here: https://github.com/ksw2000/hackmd-to-html-cli/blob/main/layout.html

{{main}} renders main content of markdown.
{{lang}} renders lang property if there are yaml metadata about lang in markdown file. e.g. lang="zh-TW"
{{dir}} renders dir property if there are yaml metadata about dir in markdown file. e.g. dir="ltr"
{{meta}} renders meta tag if there are yaml metadata about title, description, robots orimage. e.g. <meta name="robots" content="noindex">

Develop

npm run lint to check the format of source code.
npm run example runs example for this package, which generates result from ./example and places them in ./output.
npm test runs unit test files whose filenames end with .test.ts

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.