Generate Markdown specs automatically from Haskell parsers (jbfl DSL and JBeam)

[webdevred]

Summary

I want to generate Markdown documentation/specifications for my DSL and JBeam languages directly from the Haskell parsers.

I already have working Megaparsec parsers for both jbfl and JBeam, and I’m considering writing code that introspects or parses the parser definitions themselves to extract a BNF-like AST. From that AST, I could automatically produce Markdown documentation (grammar specs, examples, etc).

Motivation

I don’t want to maintain language specifications manually.
Manual specs inevitably drift out of sync with the actual implementation — especially when experimenting with syntax, adding new features, or refactoring parsers.

Right now, the parser code is the source of truth for what the language actually is.
So the ideal workflow is:

• The parser defines the grammar.
• The documentation is generated from the parser.
• The spec is always up-to-date by construction.

Alternatives considered

1. Write BNF first and generate parsers from it
   Possible, but I’d lose many of the benefits of Megaparsec — composability, type safety, and great error handling.

2. Maintain Markdown specs manually
   Not sustainable, and quickly diverges from the implementation.

3. Generate Haddock documentation
   Haddock is useful for API docs, but not ideal for describing grammars.
   It still requires keeping comments in sync manually, and anyone reading the docs needs to understand Haddock’s structure.
   So the “truth” still lives in two places: the parser code and the comments.

Goals

• Keep the Haskell parsers as the single source of truth.
• Automatically generate Markdown documentation/specs from them.
• Optionally visualize or export the grammar as BNF/EBNF.

Open questions

• How practical is it to introspect Megaparsec parser definitions automatically?
• Would ghc-lib-parser be suitable for extracting structure?
• How to represent combinators and alternatives in a readable BNF-like form?

Current specs

Official JBeam spec: https://documentation.beamng.com/modding/vehicle/intro_jbeam/jbeamsyntax/
Current version of jbeam-edit jbfl DSL spec: https://github.com/webdevred/jbeam_edit/blob/master/JBFL_DOCS.md