@erkkah/nomnomd

nomnomd = nomnoml + md

nomnomd processes Markdown with included or referenced nomnoml diagrams and produces HTML.

I threw together nomnomd to write documentation for a project where I wanted to keep all docs in the code repo and depend on as few external tools as possible.

Each generated HTML file is self-contained.

Markdown extensions

Embedded nomnoml diagrams

By using the nomnoml fence code, a diagram can be written directly in a code block:

```nomnoml
[A] -> [B]
```

nomnoml files (ending in .noml or .nomnoml) can be referenced as images:

![Class Diagram](./classes.noml)

In both cases, the generated SVG is embedded in the resulting HTML file. The generated HTML adds a CSS-based zoom function, to view detailed diagrams up close.

Markdown file links, listings and includes

You can link to other Markdown files:

[A link][linked.md]

nomnomd overloads the Markdown image syntax to mean "in place" or "here". This allows for creating file lists

![](./docs)

and including files:

![Changelist](changelist.md)

Note that only Markdown (.md) files are listed and included.

List entries can be decorated by entering a pupa template as alt text, like this:

![- {title}](./docs)

The template will use data from the JSON frontmatter of each listed file.

Emojis

All GitHub emojis should work. ✅

Themes

sheetleeten theme files can be used to override the default theme:

$ npx @erkkah/nomnomd --theme coffee.css docs.md

Creating themes is easy, basically just setting four colors and two fonts.

Syntax highlighting is provided by highlight.js. The default theme can be changed by specifying a theme name:

$ npx @erkkah/nomnomd --hltheme rainbow docs.md

Working with nomnomd

Usage:
    nomnomd [options] <files...>

    Options:
        [--help]
        [--out DIR]
        [--theme FILE]
        [--hltheme <hljs-theme>]
        [--serve <port>]
        [--recursive|-r]

Simply running nomnomd with a set of Markdown files generates the resulting HTML files in the build output folder.

If recursive mode is turned on, all directories passed nomnomd will be traversed, and all .md files found will be processed.

During development, nomnomd can be run with the --serve flag to launch a little watching, hot-reloading development server on the given port. No output is written in serve mode.