ksw2000 / hackmd-to-html-cli

A CLI/Package converts HackMD markdown to HTML.

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

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

1. npm run lint to check the format of source code.
2. npm run example runs example for this package, which generates result from ./example and places them in ./output.
3. 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	HackMD Default 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	✅	✅
Typographic replacements	✅	✅
Blockquotes	✅	✅
List	✅	✅
Tables	✅	✅
Links	✅	✅
Link with title	✅	✅
Autoconverted link	✅	✅
Image	✅	✅
- normal	✅	✅
- with title	✅	✅
- given size	✅	✅
Footnotes	✅	✅
Definition list	✅	✅
Abbreviations	✅	✅

Support Externals

Features	hmd2html	HackMD Default 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.

hackmd-to-html-cli's Issues

Notice HackMD

Maybe you should notice hackmdio(or their dev Yukaii) to co-op with this project?