Markdown 📄¶

markdown provides tools for processing Markdown documentation trees according to the Enola Knowledge Format (EKF) and related specifications such as Markdown Magic Links.

It supports in-place canonical formatting, resolving internal magic links, generating dynamic directory index pages, and converting Markdown documentation hierarchies into static HTML sites with bundled assets.

Screencast¶

format¶

format (aliases: fmt) canonicalizes and formats Markdown files in place:

Formats Markdown tables with cleanly aligned columns.
Normalizes Markdown formatting according to canonical standards.
Recursively processes directories or formats a single file.

$ ./enola markdown format --help
Usage: enola markdown format [-hVv] PATH
Formats Markdown files in place
      PATH        Directory or file containing Markdown files to format
  -h, --help      Show this help message and exit.
  -v, --verbose   Error verbosity; specify multiple -v options to increase it;
                    e.g. -v -v -v or -vvv.
  -V, --version   Print version information and exit.

generate-md¶

generate-md resolves magic links and generates category indexes for Markdown trees:

Ingests source Markdown files from the input directory.
Synthesizes index.md category landing pages for directories.
Resolves magical links ([[...]]) into standard Markdown links with automatically extracted titles.
Copies non-Markdown asset files to the output directory.

$ ./enola markdown generate-md --help
Usage: enola markdown generate-md [-hVv] INPUT-DIR OUTPUT-DIR
Resolves magic links and generates indexes for Markdown files
      INPUT-DIR    Input directory containing Markdown files
      OUTPUT-DIR   Output directory for resolved Markdown files
  -h, --help       Show this help message and exit.
  -v, --verbose    Error verbosity; specify multiple -v options to increase it;
                     e.g. -v -v -v or -vvv.
  -V, --version    Print version information and exit.

generate-html¶

generate-html generates static HTML documentation sites from Markdown files:

Ingests source Markdown files and resolves magic links and indexes in memory.
Converts Markdown files into standalone HTML pages with styling, navigation, Mermaid diagrams support, and syntax highlighting.
Adds an Edit link pointing to the configured EDIT-BASE-URL (e.g. on GitHub).
Bundles wiki.css, wiki.js, Mermaid scripts, and copies other asset files into the output directory.

$ ./enola markdown generate-html --help
Usage: enola markdown generate-html [-hVv] INPUT-DIR OUTPUT-DIR EDIT-BASE-URL
Generates HTML and assets from Markdown files
      INPUT-DIR       Input directory containing Markdown files
      OUTPUT-DIR      Output directory for HTML files
      EDIT-BASE-URL   Base URL for the Edit button
  -h, --help          Show this help message and exit.
  -v, --verbose       Error verbosity; specify multiple -v options to increase
                        it; e.g. -v -v -v or -vvv.
  -V, --version       Print version information and exit.

CLI Options¶

$ ./enola help markdown
Usage: enola markdown [-hVv] [COMMAND]
Markdown tools
  -h, --help      Show this help message and exit.
  -v, --verbose   Error verbosity; specify multiple -v options to increase it;
                    e.g. -v -v -v or -vvv.
  -V, --version   Print version information and exit.
Commands:
  format, fmt    Formats Markdown files in place
  generate-md    Resolves magic links and generates indexes for Markdown files
  generate-html  Generates HTML and assets from Markdown files