\n```\n\nRead [usage examples](#examples) to learn how to use the CLI.\n\n### Options\n\n| Option | Description |\n| ------------------------------- | --------------------------------------------- |\n| `-V, --version` | Output the version number |\n| `-d, --dest [value]` | Destination path (default: next to .md files) |\n| `-j, --join` | Concatenate all files before compilation |\n| `-l, --layout [value]` | HTML layout |\n| `-t, --theme [value]` | CSS theme |\n| `-s, --highlight-style [value]` | Syntax highlighting style |\n| `-n, --numbered-headings` | Enable numbered headings |\n| `-c, --code-copy` | Enable copy code button |\n| `-m, --mermaid` | Enable mermaid |\n| `-e, --embed-mode [value]` | Embed external resources (default: `default`) |\n| `-x, --extension [value...]` | Extension scripts |\n| `-w, --watch` | Watch input files and compile on change |\n| `-h, --help` | Output usage information |\n\n#### Destination (`--dest`)\n\nThe destination path can be used to change where output HTML files are written.\n\n#### Join (`--join`)\n\nThe `--join` option concatenates all Markdown source files in one (`MERGED.md`)\nbefore running the compilation (→ `MERGED.html`):\n\n- _Sorting_: `README.md` and `index.md` files first, other `.md` files and\n sub-directories next\n- _Front matter_: remove YAML (`---`), TOML (`+++`) or JSON (`;;;`) front matter\n from source files\n- _Titles_: refactor titles level (`#` syntax only) according to path depth\n- _Paths_: refactor relative paths (`[<...>](./<...>)`)\n- _Table of contents_: remove table of contents tokens from child pages\n\nThis feature, _experimental and not very configurable for the moment_, can be\nvery useful to export a multi-files documentation into a single HTML file.\n\n#### Layout (`--layout`)\n\nA layout is an HTML template used as a base for the output HTML file, e.g.:\n\n```html\n\n\n\n \n {{ title }}\n {{ styles }} \n\n\n{{ body }} \n\n{{ scripts }} \n\n```\n\nThe `--layout` option can receive the name of a [preset](./assets/layouts/)\n(e.g. `page` for `page.html`) or the path to a custom layout file\n(`path/to/my-layout.html` or a HTTP URL).\n\n#### Theme (`--theme`)\n\nA theme is a CSS stylesheet included in the HTML layout.\n\nThe `--theme` option can receive the name of a preset (e.g. `github`)\nor the path to a custom theme file (`path/to/my-theme.css` or an HTTP URL).\n\n#### Highlight style (`--highlight-style`)\n\nHighlight style enables syntax highlighting of code blocks by including the\nrequired script and style in the HTML layout.\n\nThe `--highlight-style` option can receive the name of a\n[Hightlight.js style](https://github.com/highlightjs/highlight.js/tree/main/src/styles)\n(file name without extension, e.g. `monokai`) or the path to a custom style\nfile (a local path or an HTTP URL).\n\n#### Additional features\n\n_Markdown To Document_ includes additional features:\n\n- **Numbered headings** (`--numbered-headings`): enable automatic headings\n numbering (`h2` to `h6`, e.g. `1.1.1.`)\n- **Code copy** (`--code-copy`): add a button Copy in each\n code block to easily copy the block content\n- **Mermaid** (`--mermaid`): add support for [mermaid](https://mermaid-js.github.io/mermaid/)\n diagrams using fenced code blocks (` ```mermaid `), e.g.:\n\n````markdown\n```mermaid\nflowchart LR\n Markdown --mdtodoc--> HTML\n```\n````\n\n```mermaid\nflowchart LR\n Markdown --mdtodoc--> HTML\n```\n\n#### Embed mode (`--embed-mode`)\n\nThe `--embed-mode` option allows to inline externally referenced resources\n(JS, CSS and images) to output a single HTML file without external dependencies\n(it can lead to a large output file).\n\n3 modes are available:\n\n- `light`: inline light scripts (< 16 KB), stylesheets and light images\n (< 16 KB)\n- `default`: inline light scripts (< 16 KB), stylesheets and all images\n (**default**)\n- `full`: inline everything\n\n#### Extensions (`--extension`)\n\nThe `--extension` option allows to provide paths to extension scripts to\nfurther customize document generation.\n\nAn extension is a JavaScript file using ECMAScript modules format with up to\nfive exported functions corresponding to available hooks, taking an object in\nparameter, doing some modifications on it, and returning it.\n\n```js\nexport function hookName({ arg1, arg2, ... }) {\n // Modify then return arguments\n return { arg1, arg2, ... };\n}\n```\n\nThese hooks (and their arguments) are available:\n\n- **`postInit`**: called after compiler initialization and before source file\n loading\n - `mdIt` (`MarkdownIt`): Markdown.it instance, configure it further, or even\n load additional plugins with the `.use(...)` method\n- **`preCompile`**: called after source file loading and before Markdown\n compilation\n - `md` (`string`): Markdown document\n- **`preRender`**: called after Markdown compilation and before template/layout\n rendering\n - `title` (`string`): HTML document title\n - `styles` (`string[]`): CSS stylesheet URLs\n - `scripts` (`string[]`): JS scripts URLs\n - `body` (`string`): HTML document body\n- **`preInline`**: called after rendering and before inlining\n - `html` (`string`): full HTML document\n- **`preWrite`**: called after inlining and before writing to the output file\n - `html` (`string`): full HTML document\n - `path` (`string`): output file path\n\n### Examples\n\n**Compile a single Markdown file (`doc.md`) into HTML (`doc.html`)**\n\n```shell\nmdtodoc doc.md\n```\n\n**Watch and compile multiple Markdown files using glob syntax**\n\n```shell\nmdtodoc *.md --watch\n```\n\n**Compile multiple Markdown files into a single HTML file (`MERGED.html`)**\n\n```shell\nmdtodoc *.md --join\n```\n\n**Improve the HTML output with a layout, a theme and a highlight style**\n\n```shell\nmdtodoc doc.md --layout \"page\" --theme \"github\" --highlight-style \"atom-one-light\"\n```\n\nThe compiled Markdown is now included into the predefined layout `page`\nand some CSS styling is added directly into the HTML file.\n\n**Enable additional features**\n\n```shell\nmdtodoc doc.md -l \"page\" -t \"github\" -s \"atom-one-light\" --numbered-headings --code-copy --mermaid\n```\n\nHTML headings are now automatically numbered, a Copy button\nis added in each `` code block to copy the content, and diagrams\nare generated from `mermaid` code blocks (` ```mermaid `).\n\n**Embed all externally referenced resources**\n\n```shell\nmdtodoc doc.md -l \"page\" -t \"github\" -s \"atom-one-light\" -n -c --embed-mode \"full\"\n```\n\nAll external resources (CSS, JS and images) referenced in the Markdown file\nare now embedded into the output HTML file.\n\n**Use a custom layout (local file) and a custom highlight style (URL)**\n\n```shell\nmdtodoc doc.md -l \"./assets/layouts/page.html\" -t \"github\" -s \"https://raw.githubusercontent.com/highlightjs/highlight.js/main/src/styles/monokai.css\" -n -c\n```\n\nRead [options documentation](#options) for more information on how to use\n`--layout`, `--theme` and `--highlight-style` options.\n\n**Use an extension to do more customization**\n\n```shell\nmdtodoc doc.md -l \"page\" --extension \"./test/data/extension/uppercase_title.js\"\n```\n\nTitle in the output HTML document (`[...]`) is now uppercase.\n\n**Export a Markdown documentation in a GitLab CI pipeline**\n\nIn a GitLab repository with Markdown files inside the `docs/` folder,\nthe following job can be defined (in `.gitlab-ci.yml`) to export all the\ndocumentation as a single HTML file:\n\n```yaml\nexport-doc:\n stage: doc\n image: node:lts\n before_script:\n - npm i markdown-to-document -g\n script:\n - mdtodoc \"docs/**/*.md\" --join -l \"page\" -t \"github\" -s \"atom-one-light\" -n -c\n - mv docs/MERGED.html ./docs.html\n artifacts:\n paths:\n - docs.html\n```\n\n## Resources\n\n### Useful apps, packages & more\n\n#### Code editors\n\nAlthough Markdown documents are simple text files and can be written using\nbasic text editors, most code editors provide features and extensions to make\nwriting these documents easier, e.g.:\n\n- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)\n (Visual Studio Code)\n- [MarkdownEditing](https://packagecontrol.io/packages/MarkdownEditing) (Sublime Text)\n\n#### Formatting\n\nMarkdown files can be easily formatted with [code editors](#code-editors)\nusing built-in features or additional extensions but code formatters like\n[Prettier](https://prettier.io/) also do a good job:\n\n```shell\nnpm install --global prettier\nprettier --check \"*.md\"\nprettier --write \"*.md\"\n```\n\n### Markdown compiler\n\n_Markdown To Document_ uses the [Markdown.it](https://github.com/markdown-it/markdown-it)\ncompiler and the following plugins to generate HTML code from Markdown:\n\n- `markdown-it-abbr` - Abbreviation (``) tag support\n- `markdown-it-anchor` - Header anchors (permalinks) support\n- `markdown-it-container` - Custom block containers (`:::`) support\n- `markdown-it-deflist` - Definition list (``) tag support\n- `markdown-it-emoji` - Emoji syntax (`:memo:` → :memo:) support\n- `markdown-it-footnote` - Footnotes (`[^1]`) support\n- `markdown-it-ins` - Inserted (``) tag support\n- `markdown-it-mark` - Marked (``) tag support\n- `markdown-it-sub` - Subscript (``) tag support\n- `markdown-it-sup` - Superscript (``) tag support\n- `markdown-it-task-lists` - Task lists (`- [ ]` / `- [x]`) support\n- `markdown-it-toc-done-right` - Table of contents (`[[toc]]`) support\n\nAdditional features also use the following packages:\n\n- [highlight.js](https://highlightjs.org/) - JavaScript syntax highlighter with\n language auto-detection and zero dependencies\n- [web-resource-inliner](https://github.com/jrit/web-resource-inliner) - Inlines\n img, script and link tags into the same file\n- [clipboard.js](https://clipboardjs.com/) - A modern approach to copy text to\n clipboard\n- [chokidar](https://github.com/paulmillr/chokidar) - Minimal and efficient\n cross-platform file watching library\n- [mermaid](https://mermaid.js.org/) - Generate diagrams from markdown-like text\n\nOpen [package.json](./package.json) to see the full list of dependencies.\n\n## Development\n\n- Link the `mdtodoc` command for development: `npm link`\n - Unlink: `npm unlink`\n- Format code with Prettier: `npm run format[:check]`\n- Lint code with ESLint: `npm run lint`\n- Build assets: `npm run build:assets`\n- Run tests: `npm run test[:coverage]`\n- Upgrade dependencies: `npx npm-check-updates -u`\n\n## License\n\n**Markdown To Document** is licensed under the GNU General Public License.\n","readmeFilename":"README.md"}