HACKER Q&A
📣 mbonnet

What do you use for writing and delivering documents in many formats?


I work in a space where more traditional customers often want physical documents - PDFs, or even printed documents - while others ask for things like readthedocs-esque sites. What tools do you use for this, where you can write documentation in one place, and deliver multiple kinds of end-user formats?

Note that this isn't just code docs, but procedural/informative/tutorial type docs as well.

  👤 realityfactchex Accepted Answer ✓
Markdown.

Then Pandoc can convert that .md file to a nice formal PDF using your template, so it looks like it came from LaTeX and is suitable for academic-style reading. This is good for PDF user manuals.

Or the Markdown can be put into a markdown-friendly slide engine (take your pick) and a slide deck can be made from it.

Or the Markdown could go into a Markdown-friendly wiki engine (take your pick) and be used as documentation there.

Or the Markdown could go into a Markdown-to-richtext editor to be copy-pasted into chat apps that don't have good text-based formatting editors built-in.

Basically I think Markdown is the top universal format for write once, use anywhere. Just use a good collection off "destination endpoints", and the first time delivering to that "endpoint", it might take figuring out the best way to get it there. IME there are always very nice ways, since people love Markdown, and not much come close to its universality.

Markdown even works in Obsidian, etc.

👤 solardev
Markdown, HTML, and mdast libs / unified tools: https://unifiedjs.com/

Epub might also be another format to consider.