{"id":19935947,"url":"https://github.com/gaelgirodon/markdown-to-document","last_synced_at":"2025-07-06T13:34:23.170Z","repository":{"id":48346537,"uuid":"199087306","full_name":"GaelGirodon/markdown-to-document","owner":"GaelGirodon","description":"A command-line tool to easily generate HTML documents from Markdown files","archived":false,"fork":false,"pushed_at":"2025-03-23T17:17:04.000Z","size":1107,"stargazers_count":42,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T09:04:32.522Z","etag":null,"topics":["cli","document","docx","html","markdown","merge","mermaid","pdf","word"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GaelGirodon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-26T22:30:04.000Z","updated_at":"2025-01-26T07:47:39.000Z","dependencies_parsed_at":"2022-08-24T14:49:43.656Z","dependency_job_id":"df67b31d-4b36-4779-8bb4-82aaa46d2aee","html_url":"https://github.com/GaelGirodon/markdown-to-document","commit_stats":{"total_commits":126,"total_committers":1,"mean_commits":126.0,"dds":0.0,"last_synced_commit":"81cd68862127e72d058b2de7b8008758f45bf83b"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaelGirodon%2Fmarkdown-to-document","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaelGirodon%2Fmarkdown-to-document/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaelGirodon%2Fmarkdown-to-document/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaelGirodon%2Fmarkdown-to-document/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GaelGirodon","download_url":"https://codeload.github.com/GaelGirodon/markdown-to-document/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247634587,"owners_count":20970560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","document","docx","html","markdown","merge","mermaid","pdf","word"],"created_at":"2024-11-12T23:22:44.649Z","updated_at":"2025-04-07T10:27:26.244Z","avatar_url":"https://github.com/GaelGirodon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown To Document\n\n[![version](https://img.shields.io/npm/v/markdown-to-document?color=informational\u0026style=flat-square)](https://www.npmjs.com/package/markdown-to-document)\n[![license](https://img.shields.io/npm/l/markdown-to-document?color=informational\u0026style=flat-square)](https://raw.githubusercontent.com/GaelGirodon/markdown-to-document/main/LICENSE)\n[![node](https://img.shields.io/node/v/markdown-to-document?style=flat-square)](https://nodejs.org/download/)\n[![build](https://img.shields.io/github/actions/workflow/status/GaelGirodon/markdown-to-document/main.yml?branch=develop\u0026style=flat-square)](https://github.com/GaelGirodon/markdown-to-document/actions/workflows/main.yml)\n[![tests](https://img.shields.io/endpoint?style=flat-square\u0026url=https%3A%2F%2Fgist.githubusercontent.com%2FGaelGirodon%2Ffbde4d59b7dd3c4f2cc9c4fea3497ae1%2Fraw%2Fmarkdown-to-document-junit-tests.json)](https://github.com/GaelGirodon/markdown-to-document/actions/workflows/main.yml)\n[![coverage](https://img.shields.io/endpoint?style=flat-square\u0026url=https%3A%2F%2Fgist.githubusercontent.com%2FGaelGirodon%2Ffbde4d59b7dd3c4f2cc9c4fea3497ae1%2Fraw%2Fmarkdown-to-document-cobertura-coverage.json)](https://github.com/GaelGirodon/markdown-to-document/actions/workflows/main.yml)\n\nA command-line tool to easily generate HTML documents from Markdown files.\n\n\u003e The original purpose of this tool was to provide an alternative to using\n\u003e Microsoft Word to write and send technical documents.\n\u003e\n\u003e **Use cases:** replace `docx` and `pdf` files with Markdown (storage in Git,\n\u003e editing, ...) and HTML (export, sending by email, ...) files, export a\n\u003e multi-files documentation into a single HTML file, etc.\n\n## Install\n\nInstall the CLI globally using NPM ([Node.js](https://nodejs.org/) \u003e= 20):\n\n```shell\nnpm install markdown-to-document -g\n```\n\n\u003e **Linux users:** `EACCES` permissions errors when installing packages globally?\u003cbr\u003e\n\u003e → Follow [this guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)\n\u003e to resolve them.\n\n## Usage\n\nCompile Markdown files (`path`) into HTML documents.\n\n```shell\nmdtodoc [options] \u003cpath...\u003e\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 (`[\u003c...\u003e](./\u003c...\u003e)`)\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\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n  \u003c!--        ⬐ Markdown document title included here --\u003e\n  \u003ctitle\u003e{{ title }}\u003c/title\u003e\n  {{ styles }} \u003c!-- ← CSS styles (theme, highlight styles, etc.) included here --\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n{{ body }}     \u003c!-- ← Compiled Markdown included here --\u003e\n\u003c/body\u003e\n{{ scripts }}  \u003c!-- ← JS scripts included here --\u003e\n\u003c/html\u003e\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 \u003ckbd\u003eCopy\u003c/kbd\u003e 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--\u003e HTML\n```\n````\n\n```mermaid\nflowchart LR\n  Markdown --mdtodoc--\u003e 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 (\u003c 16 KB), stylesheets and light images\n  (\u003c 16 KB)\n- `default`: inline light scripts (\u003c 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 \u003ckbd\u003eCopy\u003c/kbd\u003e button\nis added in each `\u003cpre\u003e` 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 (`\u003ctitle\u003e[...]\u003c/title\u003e`) 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 \u0026 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 (`\u003cabbr\u003e`) tag support\n- `markdown-it-anchor` - Header anchors (permalinks) support\n- `markdown-it-container` - Custom block containers (`:::`) support\n- `markdown-it-deflist` - Definition list (`\u003cdl\u003e`) tag support\n- `markdown-it-emoji` - Emoji syntax (`:memo:` → :memo:) support\n- `markdown-it-footnote` - Footnotes (`[^1]`) support\n- `markdown-it-ins` - Inserted (`\u003cins\u003e`) tag support\n- `markdown-it-mark` - Marked (`\u003cmark\u003e`) tag support\n- `markdown-it-sub` - Subscript (`\u003csub\u003e`) tag support\n- `markdown-it-sup` - Superscript (`\u003csup\u003e`) 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelgirodon%2Fmarkdown-to-document","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaelgirodon%2Fmarkdown-to-document","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelgirodon%2Fmarkdown-to-document/lists"}