njnmdoc

From: Neal Fultz <neal@njnm.co>

<style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>

njnmdoc is a light text-based static site generator descending from jemdoc. Although the majority of the code has changed, the core ideas remain the same. It takes a text file written with markdown, an optional configuration file and an optional menu file, and makes websites that look something like this one.

Version 8.1.0 was released on 2019-06-05. See the release notes.

Download njnmdoc or contribute on Github

Goals

• Simple, consistent syntax via Markdown (multiple backends).
• \(\LaTeX\) equation support via KaTex.
• Portability. The (single) njnmdoc Python script + your input file → html.
• Based on CSS so formatting and layout specifics are independent of content.
• Produces clean, standards-compliant HTML5.
• Minimal bells and whistles.

Configuration

Unlike the original jemdoc program, njnmdoc does not have a configuration file per se - instead, configuration is done via python scripts. A script can be referenced on the command line using the -c option, and it will then be evaluated in memory.

The default configuration can be exported using

njnmdoc --show-config

Metadata

For the various pieces of HTML that must be included outside the article, additional metadata is stored in memory as key-value pairs.

Currently, the following keys are used:

• css - URL to default style sheet
• lastupdated - Date string of timestamp
• menu - menu file
• title - title of document

Metadata can be set on the command line using the -e option:

njnmdoc -e KEY=VALUE -e KEY2=VALUE2 file.md

Modelines

File-specific metadata can be specified by placing a specific comment as the first line of a markdown file.

<!-- njnmdoc: title="My Title" css="mystyle.css" -->

Each attribute of the comment tag will be added to the metadata when processing the file.

Markdown

njnmdoc supports the following markdown processors:

• mdown_python - markdown python package
• mdown_python_gfm - markdown in python with GitHub Flavored Extensions
• mdown_markdown - markdown perl script (detected on $PATH)
• mdown_pandoc - pandoc document converter
• mdown_github - GitHub Markdown API

The most appropriate processor will be autodetected by default, but by setting the --markdown CLI option that can be overridden.

There are, unfortunately, minor differences in the output generated by the various processors. Caveat emptor.

Math Mode

Math support is provided by KaTex:

$$ e^{-x^2/2} $$

Menus

A menu can be inserted into each document in two ways:

• By specifying a menu block directly in a configuration script.
• By providing a menu metadata item containing a filename. That file, if it exists, will be piped through the markdown handler, and included in the navigation block. MENU is the default filename.

License

Copyright (©) 2007-2012 Jacob Mattingley, 2012-2015 Wonseok Shin, 2019 Neal Fultz

njnmdoc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

njnmdoc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.