{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreicbftn3ze2qozihazvs224kcr6ybklmvne4bou2igfu7ir2gmry3m",
    "uri": "at://did:plc:t4aigbwuwix7x3q42qzjc6mn/app.bsky.feed.post/3mg4zlunepkv2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiarvja3nxyesd2ra34odtnibzd4b4qbhg4btcjt2gtkl3pgke3mla"
    },
    "mimeType": "image/jpeg",
    "size": 22024
  },
  "path": "/link/535/17287905/generating-man-pages-with-apex",
  "publishedAt": "2026-03-02T14:00:00.000Z",
  "site": "https://brett.trpstra.net",
  "tags": [
    "apex.1.html",
    "apex.1.md",
    "CHANGELOG.md",
    "on Mastodon",
    "Bluesky",
    "Twitter",
    "Click here if you'd like to help out.",
    "Mastodon",
    "GitHub",
    "everywhere else"
  ],
  "textContent": "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.\n\nMan 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.\n\n**`-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`.\n\n**`-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.\n\n### See it in action\n\nThe Apex man page is available as HTML and as Markdown:\n\n  * **HTML (standalone):** apex.1.html\n  * **Markdown source:** apex.1.md\n\n\n\nBoth are generated from the same Markdown; the HTML is what you get with `apex -t man-html -s` (plus any site styling).\n\n### What else is new\n\nHighlights from the changelog:\n\n  * **Man page creation:** `-t man` and `-t man-html` as above; Makefile uses `apex -t man` for man targets.\n  * **`-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.\n  * **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.\n  * **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.\n\n\n\nFor the full list, see CHANGELOG.md.\n\nLike or share this post on Mastodon, Bluesky, or Twitter.\n\n* * *\n\nBrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.\n\nFind Brett on Mastodon, Bluesky, GitHub, and everywhere else.",
  "title": "Generating Man Pages with Apex",
  "updatedAt": "2026-03-02T14:00:00.000Z"
}