mic92/mmdoc

Minimal Markdown Documentation

mmdoc - Minimal Markdown Documentation

mmdoc project_name src out

takes a directory like:

src
├── section1.md
├── section2.md
└── toc.md

and ouputs:

out
├── man
│   └── man1
│       ├── project_name-section1.1
│       └── project_name-section2.1
├── multi
│   ├── fuse.basic.min.js
│   ├── highlight.pack.js
│   ├── minimal.css
│   ├── mono-blue.css
│   ├── search_index.js
│   ├── search.js
│   ├── section1
│   │   └── index.html
│   └── section2
│       └── index.html
├── project_name.epub
└── single
    ├── highlight.pack.js
    ├── index.html
    ├── minimal.css
    └── mono-blue.css

That is, given a table of contents MarkDown file, and some other MarkDown files, it generates

• A single-page HTML document
• Multi-page HTML documents
• man pages (experimental)
• An ePub book (experimental)

Here are some features:

• No options.
• Fast: written in C, using cmark a very fast MarkDown parser/renderer.
• The HTML documents have syntax highlighting via highlight.js.
• The multi-page HTML documents have full-text search via fuse.js.

Extensions beyond CommonMark

In order to be useful for Documentation, it uses several CommonMark extensions available in GitHub-flavored MarkDown and Pandoc.

• Cross references

  Made with:

  # Heading {#heading-anchor-id}
  [inline]{#inline-anchor-id}
  

  Referenced with:

  [heading](#heading-anchor-id)
  [inline](#inline-anchor-id)
  

• GitHub tables

  | foo | bar |
  | --- | --- |
  | baz | bim |
  

• Admonitions

  ::: warning
  this is your last warning
  :::
  

• DD Lists

  : term 1
  
  defintion 1
  
  : term 2
  
  defintion 2
  

toc.md

toc.md is a special file for mmdoc. The order of the cross references in toc.md control the order the sections appear in the single-page HTML and ePub outputs. If a section is not referenced in toc.md it does not get included in any of the outputs.

Development

For easily development, nix with flake support is recommended. Start a development environment with:

nix develop

tests

Compile and run the test suite with:

make test

additional test: compile the nixpkgs manual

This is a temporary test that is in place while mmdoc is developed in tandem with the conversion of the nixpkgs manual to use Markdown. You can build my branch of nixpkgs-manual with:

nix build .#nixpkgs-manual