Skip to content

ksw2000/hackmd-to-html-cli

BranchesTags

Repository files navigation

hackmd-to-html-cli

NPM version

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.

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

  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.

About

A CLI/Package converts HackMD markdown to HTML.

npmjs.com/package/hackmd-to-html-cli

Topics

nodejs markdown npm hackmd

Resources

Readme

License

MIT license
Activity

Stars

23 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 14

v2.0.0 Latest
Nov 15, 2024
+ 13 releases

Contributors 2

  •  
  •  

Languages