# hackmd-to-html-cli
[](https://www.npmjs.org/package/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](https://hackmd.io/)-supported Markdown into HTML.
+ Example of input markdown: [./example/index.md](https://raw.githubusercontent.com/ksw2000/hackmd-to-html-cli/main/example/index.md)
+ Example of output html: [https://ksw2000.github.io/hackmd-to-html-cli/](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](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](https://ksw2000.github.io/hackmd-to-html-cli/webjs.html)
## Install
```sh
# CLI
npm install -g hackmd-to-html-cli
# Package
npm install hackmd-to-html-cli
```
## CLI
```sh
$ hmd2html --help
hmd2html --help
Usage: index [options]
Options:
-v, --version output the current version
-i, --input the path/url of input markdown files
-d, --dest the path of output directory (filename is generated automatically) (default: ./output)
-o, --output the path of output file (ignored if the flag -d is set) (default: "")
-l, --layout 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**
```sh
# 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/](./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` or`image`. e.g. ``
Example:
```html
{{metas}}
{{main}}
```
There are some features rendered by other dependencies. Thus, in our default layout, we include those dependencies.
## Example
### CommonJS
```js
const { Converter } = require('hackmd-to-html-cli')
const converter = new Converter();
const res = converter.render("# hello");
console.log(res.main);
```
### ES Module
```ts
import { Converter } from "hackmd-to-html-cli"
const converter = new Converter();
const res = converter.render("# hello");
console.log(res.main);
```
### Web
```js
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](https://hackmd.io/features-tw?both)
| 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 | ✅ | ``
``
``|
| description | ✅ | ``
``
`` |
| robots | ✅ | `` |
| lang | ✅ | `` |
| dir | ✅ | `` |
| image | ✅ | ``
`` |
| others | ✅ | Hide the metadata by html comment |
HackMD sets the `lang` tag and `dir` tag at the beginning of ``. hmd2html sets the the `lang` tag and `dir` tag at `` when using default layout.
## Development
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 `.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.