HN Debrief

Twenty Years of Pandoc

  • Open Source
  • Developer Tools
  • Programming

The post is John MacFarlane’s look back at twenty years of Pandoc, the document conversion tool that turns one markup format into another by parsing inputs into a common abstract syntax tree and then writing them back out in different formats. The retrospective explains how that N-readers, M-writers architecture let a small project grow into a surprisingly broad interoperability layer for Markdown, HTML, LaTeX, docx, PDF workflows, Typst, and more. It also reflects on two choices that shaped the project: using Haskell, which kept contributor volume low but quality high, and keeping the problem definition narrow enough that conversions stay meaningful instead of pretending every document system can map cleanly to every other one.

If your team moves content across formats, Pandoc is worth treating as core infrastructure rather than a niche CLI utility. The thread also points to a broader lesson for product and tooling choices: a tight intermediate representation and disciplined scope age better than trying to support every edge case with fuzzy automation.

Discussion mood

Strongly positive and grateful. People see Pandoc as rare long-lived infrastructure that quietly solves real work, and they admire both its clean architecture and the restraint that kept it useful instead of bloated.

Key insights

  1. 01

    The payoff came from the intermediate representation

    The lasting trick was not “supports many formats.” It was defining a document model strong enough to sit between them. That common abstract syntax tree is what makes the N-by-M converter story real rather than hand-wavy. Commenters tied that to a broader software lesson. The hard part is identifying the domain representation that deserves to exist, because once that is right, a lot of extension work becomes straightforward and even automatable.

    When you evaluate content tooling, look first at the internal model, not the feature list. If your own product has many inputs and outputs, invest in the canonical representation before you chase adapters.

      Attribution:
    • adamddev1 #1
    • vatsachak #1
    • tajd #1
  2. 02

    Haskell shaped the contributor pool

    Choosing Haskell appears to have filtered for contributors and hires who were comfortable with deeper engineering tradeoffs, while keeping raw applicant volume low. People with hiring experience said that scarcity was real, but so was the signal quality. The more useful point is not that Haskell is magically better. It is that language choice changes project culture, who self-selects in, and how much noise maintainers must absorb. Others added that small teams can tolerate a niche stack if they are willing to train strong engineers on the job.

    Treat stack choice as a recruiting and governance decision, not just a technical one. If you pick a niche toolchain, plan for lower funnel volume and stronger onboarding rather than expecting the market to look like JavaScript hiring.

      Attribution:
    • PeterStuer #1
    • akurilin #1
    • bluGill #1
    • tialaramex #1
  3. 03

    Pandoc turns binary docs into reviewable text

    Using Pandoc as a Git textconv layer for docx files makes otherwise opaque office documents diffable in pull requests. That is especially useful for contracts and other review-heavy workflows where redlines matter more than final layout. One commenter pushed it further by piping those diffs into CI so GitHub can post readable changes automatically when a PR modifies a docx.

    If your team still exchanges Word files with customers, legal, or partners, add a Pandoc-based diff step to version control and CI. It will make document review auditable without forcing everyone to abandon docx.

      Attribution:
    • koolba #1
    • Marsymars #1
  4. 04

    Pandoc stays useful by refusing fake conversions

    Its scope discipline is not a limitation. It is the reason people trust it. The key distinction here is between documents that mostly encode natural language and systems that encode document generation logic, product configuration, or component content management. Once formats depend on transclusion, conditionals, or domain-specific semantics, conversion stops being translation and becomes partial recompilation of a larger system. Pandoc’s credibility comes from not pretending otherwise.

    Do not promise universal import and export if your source formats carry workflow logic or domain semantics. Draw a hard line between document conversion and system migration, because users will notice when you blur them.

      Attribution:
    • lopsotronic #1
  5. 05

    People use it as plumbing, not as an app

    The striking pattern across examples was how rarely Pandoc is the center of the workflow. It is the quiet conversion layer inside shell scripts, static site generators, HTML cleanup functions, blog-to-PDF pipelines, and ad hoc publishing tools. That kind of usage says more than praise does. Software becomes durable when it disappears into other systems and keeps doing one job well for years.

    Look for opportunities to embed Pandoc behind your own internal tools instead of asking users to learn it directly. The best fit is often as a stable backend component in publishing, reporting, and knowledge workflows.

      Attribution:
    • rahimnathwani #1
    • malkosta #1
    • dannyobrien #1
    • graemep #1
    • aleks_me2 #1
    • nc55g3g #1

Against the grain

  1. 01

    LLMs can still generate simple tools

    The praise for hand-built architecture did not convince everyone that this is an either-or choice. One commenter argued you can still get simple and elegant software out of LLMs if you direct them well. That does not challenge Pandoc’s design, but it does push back on using it as proof that AI-assisted development necessarily produces messy systems.

    Do not turn admiration for well-designed legacy tools into a blanket rule against AI-assisted implementation. Judge whether the generated code preserves a clean model and maintainable boundaries.

      Attribution:
    • whalesalad #1
  2. 02

    For new projects a library may be simpler

    Pandoc is convenient, but it is not automatically the right foundation for every content pipeline. One commenter noted that if you only need markdown parsing and HTML generation for a new project, using native libraries in a language like Rust can buy more flexibility and remove the dependency on an external converter plus its configuration quirks. The hard part is parsing, not emitting HTML, and you may not need Pandoc’s whole abstraction if your scope is narrow.

    Reach for Pandoc when you need broad format interoperability. If your problem is narrow and central to your product, compare it against using in-process libraries that give you tighter control.

      Attribution:
    • huijzer #1

In plain english

abstract syntax tree ↩
A structured internal representation of a document or program that captures its meaning and parts without focusing on the exact original text formatting.
CI ↩
Continuous integration, automated checks that run when code or files change in version control.
docx ↩
The Microsoft Word document file format used by modern versions of Word.
Git textconv ↩
A Git feature that converts files into a text representation for diffs, making binary or complex formats easier to review.
Haskell ↩
A functional programming language known for strong type systems and a style that fits parsing, transformations, and compiler-like tools.
LaTeX ↩
A text-based document preparation system widely used for technical and academic writing, especially when precise formatting is needed.
Pandoc ↩
An open source command-line tool and library for converting documents between markup and publishing formats such as Markdown, HTML, LaTeX, docx, and PDF.
PDF ↩
Portable Document Format, a file format for fixed-layout documents that look the same across devices.
PR ↩
Public relations, the practice of managing how a company communicates with the public and media.
transclusion ↩
A way of building a document by including content from other files or sources rather than writing it all in one place.
Typst ↩
A newer markup-based typesetting system for creating formatted documents and PDFs.

Reference links

Pandoc-related tools and demos

  • Pandoc web app
    A browser-based version of Pandoc compiled to WebAssembly, mentioned as a way to try Pandoc without local install.
  • djot
    The Pandoc author's newer markup format, brought up as a more precisely specified alternative to Markdown.

Personal tools and workflow examples

Author background