Why Markdown/AsciiDoc versus Libre Office or other word processor?

Libre Office and other word processor applications are the traditional way to produce PDF documents. They tend to do an excellent job, especially when one learns the art of template wizardry.

Both Markdown and AsciiDoc use simple text files, along with markup for various effects. The markup available in both is limited, but cover a large portion of what is needed to produce documents.

As simple text files, Markdown and AsciiDoc are both easy to store in Git, or other systems, alongside our code.

The 80% rule has made Markdown a popular choice for technical projects using programmers text editors, like Visual Studio Code, and source code control systems like Git.

Bridging the gap from easy-to-edit to great-PDF-production

PDF Document Maker makes it possible to transition from an 80% solution to a 95% (or more) solution.

• A curated set of Markdown extensions increase what we can do while staying in the easy-to-edit paradigm.
• Excellent diagramming support using PlantUML or Mermaid integrates nicely.
• CSS lets us create top-notch customized visual effects just by adding class or ID specifiers.
• The Mahabhuta server-side DOM processing engine lets us create custom HTML tags or custom DOM manipulation. This creates an endless realm of possibilities.
• Custom templates let us tailor the presentation however we desire.

For example, with the above it is easy to extract information from an external data source like OpenAPI specifications or JSON schemas. That data can be formatted using templates and CSS into tables describing API endpoints, data types, and more.

Easily reuse documentation between a PDF, and online

PDF Document Maker is based on AkashaCMS, a static website content management system. The content files used in a PDF Document Maker project can easily be used in an AkashaCMS website project.

For example, the PDF Document Maker guide (online version) is also available in PDF.