I’ve been using a combination of Pandoc and other tools to generate the man page for Apex from Markdown. As Apex nears a 1.0 release, I figured it should be able to generate man pages on its own.

Man pages are what gets shown when you run man COMMAND in Terminal. They use roff formatting, which is a pain to write as a human. Writing documentation in Markdown is much easier. Apex can now turn your Markdown into roff man pages or styled HTML man docs. Two output formats cover both classic terminals and the web.

-t man turns Markdown into roff (the traditional man-page source). Use it to generate apex.1, my-tool.1, and so on, then install them with make install or your package manager. No pandoc or go-md2man needed: after make build, make man runs the built apex binary with -t man to produce the man pages. Write your docs in Markdown and keep a single source for both the website and man apex.

-t man-html turns the same Markdown into HTML. Without -s you get a content-only snippet (no wrapper, no nav), handy for embedding. With -s (standalone) you get a full page: fixed left sidebar TOC (NAME, SYNOPSIS, DESCRIPTION, etc.), a large headline from the NAME section, and optional custom CSS via --css or --style. The document_title metadata (e.g. for APEX(1)) is used when present. You can also pass --code-highlight pygments or --code-highlight skylighting to highlight code blocks in either snippet or standalone output.

See it in action

The Apex man page is available as HTML and as Markdown:

Both are generated from the same Markdown; the HTML is what you get with apex -t man-html -s (plus any site styling).

What else is new

Highlights from the changelog:

  • Man page creation: -t man and -t man-html as above; Makefile uses apex -t man for man targets.
  • -t / --to output formats: html, json, json-filtered/ast-json/ast, markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, and now man and man-html.
  • Terminal and terminal256 renderers with theme support, --theme, and user theme files in ~/.config/apex/terminal/themes/. JSON and AST JSON output before and after filters for tooling.
  • Terminal options: --width for column wrap; Terminal.width and Terminal.theme metadata; theme list_marker style for bullets and numbers; Span_classes mapping for inline span classes.

For the full list, see CHANGELOG.md.