DocPatch vs Pandoc for Markdown Documentation: Which Tool Fits Which Job

Pandoc is a general document converter that reads and writes dozens of formats, while DocPatch is a narrow API that moves Markdown documentation into Docusaurus, MkDocs or GitBook output. If you need Word, HTML, EPUB or PDF, use Pandoc. If your job is moving a docs folder between those three documentation frameworks, DocPatch is built for that one task.

What each tool is

Pandoc is free software that runs on your own machine from the command line. In the version we tested (Pandoc 3.10) it lists 51 input formats and 75 output formats, including GitHub-flavored Markdown, HTML, Word documents and EPUB, and PDF output. None of its output formats is Docusaurus, MkDocs or GitBook, because those are documentation frameworks that use ordinary Markdown files plus their own conventions, not file formats.

DocPatch is an API you call with your Markdown. It converts Markdown documentation into Docusaurus, MkDocs or GitBook output. The input is Markdown only; it does not accept HTML, PDF, Word, Confluence or Notion files, and it does not produce PDF or HTML output. You call it with an API key, and each conversion uses one credit from your quota.

What Pandoc does to a Markdown docs file

We ran a small docs page through Pandoc (pandoc in.md -f markdown -t gfm) to see what happens to the parts documentation teams care about. The page had front matter with title, permalink, layout and weight, a heading, bold and italic text, a relative link, a table, and nested headings.

• Front matter is dropped by default. Without --standalone the front matter block disappeared from the output entirely.
• With --standalone the keys are kept but re-sorted. The block came back with its keys in alphabetical order (layout, permalink, title, weight). The permalink field stayed permalink; Pandoc does not turn it into a slug field or any other framework-specific field.
• Content mostly survives, with small normalizations. The bold and italic text, the link and the table came through unchanged. Bullet markers written with * came out as -, and a blank line was added after a heading that was directly followed by text.

None of this is a fault. Pandoc is converting between formats, and it does not know which documentation framework you are moving to. It is also the right tool when you do want a Word document, an HTML page or an EPUB from the same Markdown.

What DocPatch does

DocPatch is built for the framework move. Links, bold and italic formatting, nested headings (H1 to H3) and tables are carried through as-is, not rewritten or restructured. Front matter fields are translated into the target framework's equivalent where a real equivalent exists: for example, a Jekyll permalink field becomes a Docusaurus slug field. A field with no equivalent in the target format is dropped instead of being mistranslated.

It is deliberately narrow. It does not convert between arbitrary formats: it does not accept Word, HTML or PDF files, and it does not produce HTML or PDF output.

Which one to use

• Use Pandoc when you need output in a format other than a documentation framework (Word, HTML, EPUB, PDF), when you want a free tool that runs locally, or when you are scripting a general conversion.
• Use DocPatch when the task is moving Markdown documentation into Docusaurus, MkDocs or GitBook and you want front matter mapped to the target framework's fields.
• Use both if you publish the same Markdown to a docs site and also hand out a Word or PDF copy.

If you are unsure, convert one representative page with each tool and compare the front matter and heading output against what your target framework expects.

Frequently asked questions

Can Pandoc convert Markdown to Docusaurus, MkDocs or GitBook?

Pandoc has no output format for those frameworks. It can write Markdown (including GitHub-flavored Markdown), which those frameworks read, but it does not map front matter fields to a framework's conventions.

Does Pandoc keep front matter?

In our test it dropped front matter by default, and with --standalone it kept the keys but re-sorted them alphabetically without renaming any.

Can DocPatch convert Word or HTML files?

No. DocPatch accepts Markdown only and does not accept HTML, PDF, Word, Confluence or Notion input.

Is DocPatch a replacement for Pandoc?

No. They solve different problems: Pandoc is a general format converter, and DocPatch is a Markdown-to-documentation-framework converter.

Pandoc observations were made with Pandoc 3.10 on a sample Markdown file. Behavior can differ in other versions.