https://github.com/erkkah/nomnomd
Markdown with diagrams made easy
https://github.com/erkkah/nomnomd
diagrams documentation markdown nomnoml
Last synced: about 2 months ago
JSON representation
Markdown with diagrams made easy
- Host: GitHub
- URL: https://github.com/erkkah/nomnomd
- Owner: erkkah
- License: mit
- Created: 2021-08-22T20:05:32.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2021-10-06T16:13:25.000Z (over 4 years ago)
- Last Synced: 2026-02-27T14:55:13.128Z (4 months ago)
- Topics: diagrams, documentation, markdown, nomnoml
- Language: TypeScript
- Homepage:
- Size: 216 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
~~~markdown
```nomnoml
[A] -> [B]
```
~~~
**nomnoml** files (ending in `.noml` or `.nomnoml`) can be referenced as images:
```markdown
```
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:
```markdown
[A link][linked.md]
```
**nomnomd** overloads the Markdown image syntax to mean "in place" or "here".
This allows for creating file lists
```markdown
```
and including files:
```markdown
```
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:
```markdown
```
The template will use data from the JSON frontmatter of each listed file.
### Emojis
All [GitHub emojis](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md) should work. :white_check_mark:
## Themes
[sheetleeten] theme files can be used to override the default theme:
```shell
$ 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:
```shell
$ npx @erkkah/nomnomd --hltheme rainbow docs.md
```
## Working with **nomnomd**
```
Usage:
nomnomd [options]
Options:
[--help]
[--out DIR]
[--theme FILE]
[--hltheme ]
[--serve ]
[--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.
[sheetleeten]: https://erkkah.github.io/sheetleeten
[nomnoml]: https://nomnoml.com
[highlight.js]: https://highlightjs.org
[pupa]: https://www.npmjs.com/package/pupa