Package detail

hackmd-to-html-cli

ksw200049MIT2.0.0

A node.js CLI tool for converting HackMD markdown to HTML.

hackmd, markdown, html, cli, converter

readme

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

Layouts

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 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">

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

Development

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

changelog

Change Log

v0

v0.0.1: First release
v0.0.2: No new features
v0.0.3: Add a lot of markdown syntax
- markdown-it-sub
- markdown-it-sup
- markdown-it-footnote
- markdown-it-deflist
- markdown-it-abbr
- markdown-it-ins
- markdown-it-mark
- markdown-it-imsize
- markdown-it-table-of-contents
v0.0.4:
- Add markdown syntax
  - markdown-it-checkbox
  - markdown-it-ruby
- Replace KaTex with MathJax
- Support highlight.js
v0.0.5
- Support Mermaid
- Support Sequence
- Support Flowchart
v0.0.6
- Update README.md
v0.0.7
- Support Graphviz
- Support vega-lite
- Support Abc
- Support spoiler
- Support -b to enable hard-break mode
- Specify the start line number for code block
- Automatically generate <title> according to the first <h1>
v0.0.8
- Fix bug: line number should start at 1 not 0
- Modify index.md
- Remove unused dependencies
- Checkbox style follows hackmd
- Render MathJax directly at conversion time instead of front-end browser
v0.0.9
- Fix bug: The style of inline code
- Support externals (exclude SlideShare)
  - Youtube
  - Vimeo
  - Gist
  - Speakerdeck
  - PDF
  - Figma
v0.0.10
- Support specify your name in a blockquote
- Support specify time in a blockquote
- Support color to vary the blockquoutes
- Support render CSV as table
- Support PlantUML
v0.0.11
- Support fretboard
v0.0.12
- Change the exported class Covert to Converter
- Now we can import this package by import { Converter } from 'hackmd-to-html-cli'

v1

v1.0.0
- First publish
v1.1.0
- Support url/wildcard input
- New output flag -o
- Flag -s is changed to -i

v2

v2.0.0
- Starting support browser.
- Rename .render() to .convert()