Giter VIP home page Giter VIP logo

markdown-to-document's Introduction

Markdown To Document

version license node build tests coverage

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 docx and pdf files with Markdown (storage in Git, editing, ...) and HTML (export, sending by email, ...) files, export a multi-files documentation into a single HTML file, etc.

Install

Install the CLI globally using NPM (Node.js >= 20):

npm install markdown-to-document -g

Linux users: EACCES permissions 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.md and index.md files first, other .md files 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 (h2 to h6, 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 loading
    • mdIt (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 compilation
    • md (string): Markdown document
  • preRender: called after Markdown compilation and before template/layout rendering
    • title (string): HTML document title
    • styles (string[]): CSS stylesheet URLs
    • scripts (string[]): JS scripts URLs
    • body (string): HTML document body
  • preInline: called after rendering and before inlining
    • html (string): full HTML document
  • preWrite: called after inlining and before writing to the output file
    • html (string): full HTML document
    • path (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.:

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 support
  • markdown-it-anchor - Header anchors (permalinks) support
  • markdown-it-container - Custom block containers (:::) support
  • markdown-it-deflist - Definition list (<dl>) tag support
  • markdown-it-emoji - Emoji syntax (:memo: → 📝) support
  • markdown-it-footnote - Footnotes ([^1]) support
  • markdown-it-ins - Inserted (<ins>) tag support
  • markdown-it-mark - Marked (<mark>) tag support
  • markdown-it-sub - Subscript (<sub>) tag support
  • markdown-it-sup - Superscript (<sup>) tag support
  • markdown-it-task-lists - Task lists (- [ ] / - [x]) support
  • markdown-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 - Brings externally referenced resources, such as JS, CSS and images, into a single 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 mdtodoc command for development: npm link
    • Unlink: npm 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.

markdown-to-document's People

Contributors

gaelgirodon avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

markdown-to-document's Issues

Scaling - retaining original directories in output would be very useful

Technically this isn't a bug, but
for the benefit of using this plugin to link markdown files between each other-
it's important for tidy folder organisation when scaling.

Input:

markdownfiles/
  index.md

  cat1_files/
    c1-1.md
    c1-2.md

  cat2_files/
    c2-1.md

build

mdtodoc markdownfiles/* --dest dist/* --theme github --highlight-style atom-one-dark -l basic",
or
mdtodoc markdownfiles/* --dest dist/ --theme github --highlight-style atom-one-dark -l basic",
or
mdtodoc markdownfiles --dest dist --theme github --highlight-style atom-one-dark -l basic",

Expected output

/dist/
  index.html

  cat1_files/
    c1-1.html
    c1-2.html

  cat2_files/
    c2-1.html

Actual

`Error: Invalid source(s) (should be valid md files).

No automatic syntax highlighting for code blocks

When I run this command:
mdtodoc markdownfiles/*.md --dest dist --theme github --highlight-style atom-one-light,

I get no syntax highlighting for my code blocks
I would expect this to have syntax colouring for my html and javascript as below.

Example.md

Some js file stuf here

const x = "hello"
console.log(x)

Some html stuff here...

<!doctype html>
<html lang="en">
<body>
  <div id="app">Placeholder.</div>

  <script>
    // do something here...
    document.getElementById('app').innerHTML = 'hello world';
  </script>
</body>
</html>

them - solarized dark - as suggested in your documentation causes error

Your documentation themes do not work for me and solarized dark causes an actual error

The --highlight-style option can receive the name of a Hightlight.js style (file name without extension, e.g. solarized-dark) or the path to a custom style file (a local path or a HTTP URL).

[email protected] mdtodoc
mdtodoc markdownfiles/*.md --dest dist --theme github --highlight-style solarized-dark --layout layout/custom-layout.html

Error: Invalid highlight style 'solarized-dark': file not found or not readable.
at Style.validate (file:///C:/site/docs/node_modules/markdown-to-document/src/style.js:177:13)
at async Style.loadHighlightStyle (file:///C:/site/docs/node_modules/markdown-to-document/src/style.js:160:19)
at async Style.init (file:///C:/site/node_modules/markdown-to-document/src/style.js:77:28)
at async Processor.process (file:///C:/site/docs/node_modules/markdown-to-document/src/processor.js:63:5)

text in mermaid diagrams show incomplete

env

docker: node:lts-alpine3.10

cli

mdtodoc open_doc.md -l "page" -t "github" -s "atom-one-light" --numbered-headings --code-copy --mermaid

image

image

PS: diagram render correctly On win10 & v12.19.0 of same command

image

Rename dest file

With the --dest option, we can only provide a directory.

Would be nice to have an option or an enhancement of the --dest option to be able to rename the destination file. It'll prevent user to user more libs to move, rename or delete files.

My case is to compile README.md to dist/index.html.

And thanks for your lib, it's pretty nice ;)

Syntax highlighting not colouring code block

When I run this command:
mdtodoc markdownfiles/*.md --dest dist --theme github --highlight-style atom-one-light,

I get no syntax highlighting for my code blocks
I would expect this to have syntax colouring for my html and javascript as below.

Example.md

Some js file stuf here

const x = "hello"
console.log(x)

Some html stuff here...

<!doctype html>
<html lang="en">
<body>
  <div id="app">Placeholder.</div>

  <script>
    // do something here...
    document.getElementById('app').innerHTML = 'hello world';
  </script>
</body>
</html>

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.