About

Unix man pages use troff/nroff markup, a formatting system dating to 1970s Bell Labs. Writing raw roff by hand is error-prone. A misplaced .SH directive or unescaped backslash breaks rendering across man, groff, and mandoc implementations. This tool converts standard Markdown into valid roff output conforming to the man(7) macro package. It handles .TH title generation, section headers (.SH/.SS), font escapes (\fB, \fI), no-fill blocks (.nf/.fi), and bullet/numbered lists (.IP). The conversion runs entirely client-side with zero server dependency.

Limitations: nested blockquotes beyond two levels flatten. Table support is basic (pipe tables convert to tab-separated .TS/.TE blocks where possible, otherwise preformatted). Image references are stripped since roff has no native image support in terminal renderers. The tool assumes UTF-8 input. Pro tip: validate output with mandoc -Tlint before distribution. Remember that man page section numbers matter: section 1 is user commands, 3 is library functions, 5 is file formats.

Formulas

The converter applies a deterministic, line-by-line state machine. Each input line is classified into a block type, then inline markup is resolved via regex substitution.

InlineSub(text) applies in order:

1. ``code`` → \fBcode\fR

2. **bold** → \fBbold\fR

3. *italic* → \fIitalic\fR

4. [text](url) → text (url)

5. - (leading hyphens in flags) → \-

.TH generation: .TH "NAME" "section" "date" "source" "manual"

Where NAME = uppercased title from first # heading or user-provided name. section = integer 1 - 9 (default 1). date = current date in ISO format. source and manual are optional metadata strings.

Reference Data

Section	Content Type	Example
1	User Commands	ls, grep, git
2	System Calls	open, read, fork
3	Library Functions	printf, malloc, pthread_create
4	Special Files / Devices	/dev/null, /dev/tty
5	File Formats & Conventions	passwd, fstab, crontab
6	Games	fortune, banner
7	Miscellaneous / Macro Packages	man, ascii, regex
8	System Administration	mount, iptables, systemctl
9	Kernel Routines (Linux)	printk, kmalloc

Roff Macro	Purpose	Markdown Equivalent
.TH	Title header (name, section, date)	First # heading or filename
.SH	Section heading	## heading
.SS	Subsection heading	### heading
.PP	New paragraph	Blank line between text
.IP	Indented paragraph (list item)	* or - list item
.nf / .fi	No-fill mode (preformatted)	Fenced code block (```)
.BR	Bold/Roman alternating	Cross-references
\fB / \fR	Bold font escape	bold
\fI / \fR	Italic font escape	italic
.TP	Tagged paragraph	Definition-style lists
.RS / .RE	Relative indent start/end	Nested content / blockquotes
.BI	Bold-Italic alternating	Function signatures
\(bu	Bullet character	* or - prefix
\-	Minus sign (vs hyphen)	CLI flags like --verbose

Frequently Asked Questions

Nested bullet lists are converted using .RS (relative indent start) and .RE (relative indent end) macros wrapping inner .IP items. Each nesting level adds one .RS/.RE pair. Nesting deeper than 3 levels is supported but may render poorly in some terminal man page viewers due to column width constraints.

The language identifier (e.g., ```javascript) is stripped. The content is wrapped in .nf (no-fill) and .fi (fill) macros, preserving whitespace and line breaks exactly. Roff does not support syntax highlighting, so the language hint is discarded. The code is rendered in monospace when viewed with man or groff.

The output targets compatibility with both groff and mandoc. It uses only man(7) macros (.TH, .SH, .SS, .PP, .IP, .TP, .nf, .fi, .RS, .RE) and standard font escapes (\fB, \fI, \fR). Edge cases that may trigger mandoc warnings include very long unbroken lines (over 80 characters in preformatted blocks) and uncommon Unicode characters that lack roff glyph equivalents.

Backslashes in source Markdown are escaped as \e in roff output. Lines beginning with a period or apostrophe (which roff interprets as macro invocations) are prefixed with \& (a zero-width space) to prevent accidental macro triggering. The minus sign in CLI flags like --verbose is converted to \- which renders as a proper minus rather than a hyphen.

Yes. The tool provides fields for section number (1-9), source string (e.g., your project name and version), and manual title. If the first heading contains a pattern like COMMAND(1), the section number is auto-extracted. Otherwise it defaults to section 1 (User Commands). The date field auto-fills with the current date in ISO 8601 format.

Images (![alt](src)) are stripped entirely since roff terminals cannot render images. HTML inline tags are removed. Footnotes and definition lists (non-standard Markdown extensions) are not parsed. Horizontal rules (---) convert to a blank .PP paragraph break rather than a visual line, since roff has no standard horizontal rule macro in man(7).