Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
By Socket Research Team - Dec 02, 2024
Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
markdown-to-document
Advanced tools
markdown-to-document
A command-line tool to easily generate HTML documents from Markdown files
Markdown To Document
A command-line tool to easily generate HTML documents from Markdown files.
The original purpose of this tool was to provide an alternative to using Microsoft Word to write and send technical documents.
Use cases: replace
docxand
Install
Install the CLI globally using NPM (Node.js >= 20):
npm install markdown-to-document -g
Linux users:
EACCESpermissions errors when installing packages globally?
→ Follow this guide to resolve them.
Usage
Compile Markdown files (path) into HTML documents.
mdtodoc [options] <path...>
Read usage examples to learn how to use the CLI.
Options
| Option | Description |
|---|---|
-V, --version | Output the version number |
-d, --dest [value] | Destination path (default: next to .md files) |
-j, --join | Concatenate all files before compilation |
-l, --layout [value] | HTML layout |
-t, --theme [value] | CSS theme |
-s, --highlight-style [value] | Syntax highlighting style |
-n, --numbered-headings | Enable numbered headings |
-c, --code-copy | Enable copy code button |
-m, --mermaid | Enable mermaid |
-e, --embed-mode [value] | Embed external resources (default: default) |
-x, --extension [value...] | Extension scripts |
-w, --watch | Watch input files and compile on change |
-h, --help | Output usage information |
Destination (--dest)
The destination path can be used to change where output HTML files are written.
Join (--join)
The --join option concatenates all Markdown source files in one (MERGED.md)
before running the compilation (→ MERGED.html):
- Sorting:
README.mdandindex.mdfiles first, other.mdfiles and sub-directories next - Front matter: remove YAML (
---), TOML (+++) or JSON (;;;) front matter from source files - Titles: refactor titles level (
#syntax only) according to path depth - Paths: refactor relative paths (
[<...>](./<...>)) - Table of contents: remove table of contents tokens from child pages
This feature, experimental and not very configurable for the moment, can be very useful to export a multi-files documentation into a single HTML file.
Layout (--layout)
A layout is an HTML template used as a base for the output HTML file, e.g.:
<!DOCTYPE html>
<html lang="en">
<head>
<!-- ⬐ Markdown document title included here -->
<title>{{ title }}</title>
{{ styles }} <!-- ← CSS styles (theme, highlight styles, etc.) included here -->
</head>
<body>
{{ body }} <!-- ← Compiled Markdown included here -->
</body>
{{ scripts }} <!-- ← JS scripts included here -->
</html>
The --layout option can receive the name of a preset
(e.g. page for page.html) or the path to a custom layout file
(path/to/my-layout.html or a HTTP URL).
Theme (--theme)
A theme is a CSS stylesheet included in the HTML layout.
The --theme option can receive the name of a preset (e.g. github)
or the path to a custom theme file (path/to/my-theme.css or an HTTP URL).
Highlight style (--highlight-style)
Highlight style enables syntax highlighting of code blocks by including the required script and style in the HTML layout.
The --highlight-style option can receive the name of a
Hightlight.js style
(file name without extension, e.g. monokai) or the path to a custom style
file (a local path or an HTTP URL).
Additional features
Markdown To Document includes additional features:
- Numbered headings (
--numbered-headings): enable automatic headings numbering (h2toh6, e.g.1.1.1.) - Code copy (
--code-copy): add a button Copy in each code block to easily copy the block content - Mermaid (
--mermaid): add support for mermaid diagrams using fenced code blocks (```mermaid), e.g.:
```mermaid
flowchart LR
Markdown --mdtodoc--> HTML
```
flowchart LR
Markdown --mdtodoc--> HTML
Embed mode (--embed-mode)
The --embed-mode option allows to inline externally referenced resources
(JS, CSS and images) to output a single HTML file without external dependencies
(it can lead to a large output file).
3 modes are available:
light: inline light scripts (< 16 KB), stylesheets and light images (< 16 KB)default: inline light scripts (< 16 KB), stylesheets and all images (default)full: inline everything
Extensions (--extension)
The --extension option allows to provide paths to extension scripts to
further customize document generation.
An extension is a JavaScript file using ECMAScript modules format with up to five exported functions corresponding to available hooks, taking an object in parameter, doing some modifications on it, and returning it.
export function hookName({ arg1, arg2, ... }) {
// Modify then return arguments
return { arg1, arg2, ... };
}
These hooks (and their arguments) are available:
postInit: called after compiler initialization and before source file loadingmdIt(MarkdownIt): Markdown.it instance, configure it further, or even load additional plugins with the.use(...)method
preCompile: called after source file loading and before Markdown compilationmd(string): Markdown document
preRender: called after Markdown compilation and before template/layout renderingtitle(string): HTML document titlestyles(string[]): CSS stylesheet URLsscripts(string[]): JS scripts URLsbody(string): HTML document body
preInline: called after rendering and before inlininghtml(string): full HTML document
preWrite: called after inlining and before writing to the output filehtml(string): full HTML documentpath(string): output file path
Examples
Compile a single Markdown file (doc.md) into HTML (doc.html)
mdtodoc doc.md
Watch and compile multiple Markdown files using glob syntax
mdtodoc *.md --watch
Compile multiple Markdown files into a single HTML file (MERGED.html)
mdtodoc *.md --join
Improve the HTML output with a layout, a theme and a highlight style
mdtodoc doc.md --layout "page" --theme "github" --highlight-style "atom-one-light"
The compiled Markdown is now included into the predefined layout page
and some CSS styling is added directly into the HTML file.
Enable additional features
mdtodoc doc.md -l "page" -t "github" -s "atom-one-light" --numbered-headings --code-copy --mermaid
HTML headings are now automatically numbered, a Copy button
is added in each <pre> code block to copy the content, and diagrams
are generated from mermaid code blocks (```mermaid).
Embed all externally referenced resources
mdtodoc doc.md -l "page" -t "github" -s "atom-one-light" -n -c --embed-mode "full"
All external resources (CSS, JS and images) referenced in the Markdown file are now embedded into the output HTML file.
Use a custom layout (local file) and a custom highlight style (URL)
mdtodoc doc.md -l "./assets/layouts/page.html" -t "github" -s "https://raw.githubusercontent.com/highlightjs/highlight.js/main/src/styles/monokai.css" -n -c
Read options documentation for more information on how to use
--layout, --theme and --highlight-style options.
Use an extension to do more customization
mdtodoc doc.md -l "page" --extension "./test/data/extension/uppercase_title.js"
Title in the output HTML document (<title>[...]</title>) is now uppercase.
Export a Markdown documentation in a GitLab CI pipeline
In a GitLab repository with Markdown files inside the docs/ folder,
the following job can be defined (in .gitlab-ci.yml) to export all the
documentation as a single HTML file:
export-doc:
stage: doc
image: node:lts
before_script:
- npm i markdown-to-document -g
script:
- mdtodoc "docs/**/*.md" --join -l "page" -t "github" -s "atom-one-light" -n -c
- mv docs/MERGED.html ./docs.html
artifacts:
paths:
- docs.html
Resources
Useful apps, packages & more
Code editors
Although Markdown documents are simple text files and can be written using basic text editors, most code editors provide features and extensions to make writing these documents easier, e.g.:
- Markdown All in One (Visual Studio Code)
- MarkdownEditing (Sublime Text)
Formatting
Markdown files can be easily formatted with code editors using built-in features or additional extensions but code formatters like Prettier also do a good job:
npm install --global prettier
prettier --check "*.md"
prettier --write "*.md"
Markdown compiler
Markdown To Document uses the Markdown.it compiler and the following plugins to generate HTML code from Markdown:
markdown-it-abbr- Abbreviation (<abbr>) tag supportmarkdown-it-anchor- Header anchors (permalinks) supportmarkdown-it-container- Custom block containers (:::) supportmarkdown-it-deflist- Definition list (<dl>) tag supportmarkdown-it-emoji- Emoji syntax (:memo:→ :memo:) supportmarkdown-it-footnote- Footnotes ([^1]) supportmarkdown-it-ins- Inserted (<ins>) tag supportmarkdown-it-mark- Marked (<mark>) tag supportmarkdown-it-sub- Subscript (<sub>) tag supportmarkdown-it-sup- Superscript (<sup>) tag supportmarkdown-it-task-lists- Task lists (- [ ]/- [x]) supportmarkdown-it-toc-done-right- Table of contents ([[toc]]) support
Additional features also use the following packages:
- highlight.js - JavaScript syntax highlighter with language auto-detection and zero dependencies
- web-resource-inliner - Inlines img, script and link tags into the same file
- clipboard.js - A modern approach to copy text to clipboard
- chokidar - Minimal and efficient cross-platform file watching library
- mermaid - Generate diagrams from markdown-like text
Open package.json to see the full list of dependencies.
Development
- Link the
mdtodoccommand for development:npm link- Unlink:
npm unlink
- Unlink:
- Format code with Prettier:
npm run format[:check] - Lint code with ESLint:
npm run lint - Build assets:
npm run build:assets - Run tests:
npm run test[:coverage] - Upgrade dependencies:
npx npm-check-updates -u
License
Markdown To Document is licensed under the GNU General Public License.
FAQs
A command-line tool to easily generate HTML documents from Markdown files
We found that markdown-to-document demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Package last updated on 11 Nov 2024
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
Research
Typosquatting Cryptographic Libraries: Malicious npm Packages Threaten Crypto Developers with Keylogging and Wallet Theft
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
By Kirill Boychenko - Nov 27, 2024
Security News
Weekly Downloads Now Available in npm Package Search Results
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
By Sarah Gooding - Nov 26, 2024