MAN vs Markdown: Unix Roff Documentation vs GitHub Flavored Markdown
A technical comparison between Unix manual pages (roff / man / mdoc) and GitHub Flavored Markdown (GFM). Discover formatting conventions, macro directives, and modern web documentation.
Unix manual pages (roff/man/mdoc) were created in the 1970s by AT&T Bell Labs for terminal-based technical documentation using typesetting macros (.TH, .SH, .TP). Markdown, created in 2004 by John Gruber and standardized as CommonMark and GitHub Flavored Markdown (GFM), provides lightweight human-readable plain text formatting designed for modern web publishing, code hosting, and documentation wikis.
| FEATURE | MAN | MARKDOWN |
|---|---|---|
| Original Creator | Joe Ossanna / Bell Labs (1970s) | John Gruber / Aaron Swartz (2004) |
| Formatting Engine | roff / groff / mandoc typesetting compiler | CommonMark / GFM Markdown parsers |
| Terminal Integration | Native integration via `man` and less pagers | Requires CLI markdown viewers or terminal renderers |
| Web Ecosystem Support | Limited without HTML/roff conversion pipeline | Universal across all developer tooling and platforms |
| Syntax Complexity | High (Cryptic escape codes and macro registers) | Extremely low (Intuitive markdown characters) |
- Built directly into the Unix/Linux operating system via the universal 'man' command
- Rigid semantic conventions for command synopses, option flags, and system exit codes
- Rich typesetting macro capabilities through troff, groff, and BSD mdoc packages
- Decades of battle-tested standard technical reference literature across Unix and POSIX
- Instantly readable and editable as plain text without specialized rendering software
- Native rendering across GitHub, GitLab, modern documentation generators, and browsers
- Simple intuitive formatting syntax for bold, italics, tables, and fenced code blocks
- Effortlessly converts to HTML, PDF, EPUB, and static documentation websites
Unix man pages established the gold standard for CLI documentation, but Markdown is the undisputed format of the modern web. convrtr parses roff and mdoc manual pages into clean GitHub Flavored Markdown with preserved headers, flags, and code blocks 100% offline.
Converting files between MAN and MARKDOWN frequently? The convrtr Chrome Extension lets you right-click any image on any webpage or open the Side Panel to convert assets instantly using local WebAssembly with zero server uploads.