Hongdown: A CommonMark formatter with highly opinionated styles

Implementation
1

I’m sharing Hongdown, a CommonMark formatter I built to solve a specific
problem: existing formatters didn’t support the style conventions I needed.

Background

I initially tried using markdownlint with custom rules, but manually fixing
lint errors became tedious. An auto-formatter seemed like the natural solution,
but existing tools (remark, Prettier) didn’t support the particular quirks I
required—especially around link reference ordering and footnote placement
with context-aware heuristics.

Technical details

  • Parser: comrak (CommonMark + GFM extensions)
  • Language: Rust (edition 2024)
  • Style enforcements:
    • Setext headings (underline style) for H1/H2, ATX for H3+
    • Reference-style links with smart ordering (numeric refs sorted at end, grouped
      by section)
    • Four-tilde code fences instead of backticks
    • Consistent list formatting with - markers
    • GitHub admonitions (NOTE, WARNING, CAUTION, etc.)

CLI usage

hongdown file.md              # Format to stdout
hongdown --write *.md         # Format in place
hongdown --check docs/        # CI/linting mode
hongdown --diff file.md       # Show changes

The formatter is idempotent and configuration is optional via .hongdown.toml.

I’d love feedback from the CommonMark community—especially on edge cases,
interoperability concerns, or similar challenges others have faced!

4 Likes