January 2026

Convert macOS man Pages to HTML (or a PDF) with mandoc

The man¹ (i.e. manual) pages from macOS can get long. The more they grow, the less interest I have in scrolling them in the terminal. To avoid that, I use mandoc to make HTML versions. The command to generate a page looks like this:

mandoc -T html $(man -w ls) > ls.html

Details

Here's the breakdown:

mandoc is the command.
-T html sets the output type to HTML.
$(man -w ls) executes the standard man command with the -w flag for the ls command in this example.

The -w flag is used to return the file path to the source file for the man page instead of rendering the page itself. In the case of ls on my machine, the path is /usr/share/man/man1/ls.1. That's what gets sent to mandoc when the string is evaluated.
> ls.html sends the output from mandoc to a file named ls.html.

Styling

The output from the mandoc command doesn't have any real styling by default. You can include a call to an external stylesheet with:

-O style=FILEPATH

For example:

mandoc -T html -O style="styles.css" $(man -w ls) > ls.html

Happy Reading

I can get around man pages in the terminal alright. I'm sure there are more ways to move around than I use. Maybe I'll look into those more some day. For now, the HTML has me covered.

-a

end of line

Endnotes

I made a simple stylesheet that I use at ~/.config/mandoc/styles.css . The command I run to use it is:

mandoc -T html -O style="file:///Users/alan/.config/mandoc/styles.css" $(man -w ls) > ls.html

The stylesheet itself is:

body {
  font-family: Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif; 
  margin-inline: auto;
  max-width: 42rem;
}

If you want to open the file after it's created you can add && open FILENAME.html to the command like:

mandoc -T html $(man -w ls) > ls.html && open ls.html

I expect I'll end up making a command line function as a shortcut to this so I can do something like:

mp ls

and have it make the page with the stylesheet in a standard location and then open the file.

It'll be on commands.alanwsmith.com when it's done.

mandoc can also make PDFs. You can output the file using the > filename.pdf approach. You can also through it straight to the Preview app with:

mandoc -T pdf $(man -w ls) | open -fa Preview

You're supposed to be able to update styles by editing the file:

/usr/share/misc/mandoc.css

That file doesn't exist for me and I can't create it. I'm not worried about it enough to figure out why.

Most of the post I saw talking about how to convert man pages into HTML use man2html. It wasn't installed on my machine so I added it with homebrew. I couldn't get it to work properly though. It would cut off sections or throw out weird characters.

This page talks about how a tool called groff is no longer on macOS which seems to be part of the problem.

Whatever the case, I uninstalled man2html once I found the mandoc solution.

Thinking about this, something that would be cool to have is a little local web server where you can just punch in the command you want and have it serve up the docs for you.

References

Can man pages be converted to html and/or pdf format?

This is where I finally found the code to get the pages to output correctly.

Footnotes

^{1
⤴}

man Pages

Built-in manuals for apps and tools on mac and linux machines. They contain information on how to run commands with details on all the different options.

The default way to get at them is

man APP_NAME

For example, this is how to get the man page for the ls command:

man ls

They're the best place to go to dig into what an app/command can do.