# krazybee/goldmark architecture

> Architecture diagram of the GitHub repository krazybee/goldmark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krazybee/goldmark
- Repository: https://github.com/krazybee/goldmark

## Overview

goldmark is a pure-Go, CommonMark-compliant Markdown parser and HTML renderer. The main workflow is caller input → Markdown conversion orchestration → text reader and parser → AST → renderer → output writer. Parser syntax is organized around block and inline parsing, with extensions adding documented dialect features such as GFM tables and task lists, footnotes, definition lists, linkification, and typography. The graph reflects the sampled orchestration and module references; some extension wiring and parser internals are unsampled, so uncertain links are omitted.

Main entry points: [`parser/parser.go`](https://github.com/krazybee/goldmark/blob/master/parser/parser.go) (Parser engine), [`markdown.go`](https://github.com/krazybee/goldmark/blob/master/markdown.go) (Conversion API), [`extension/table.go`](https://github.com/krazybee/goldmark/blob/master/extension/table.go) (Tables), [`renderer/html/html.go`](https://github.com/krazybee/goldmark/blob/master/renderer/html/html.go) (HTML renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Conversion Core"]
  node_convert["Conversion API<br/>[markdown.go]"]
  node_reader["Text reader<br/>[reader.go]"]
end

subgraph group_parse["Parsing and AST"]
  node_parser["Parser engine<br/>[parser.go]"]
  node_blocksyntax["Block syntax<br/>[paragraph.go]"]
  node_links["Links and delimiters<br/>[link.go]"]
  node_attributes["Attributes<br/>[attribute.go]"]
  node_ast["Document AST<br/>[ast.go]"]
end

subgraph group_render["Rendering"]
  node_renderer["Renderer engine<br/>[renderer.go]"]
  node_html["HTML renderer<br/>[html.go]"]
end

subgraph group_extensions["Markdown Extensions"]
  node_gfm["GFM features<br/>[gfm.go]"]
  node_tables["Tables<br/>[table.go]"]
  node_footnotes["Footnotes<br/>[footnote.go]"]
  node_definitions["Definition lists<br/>[definition_list.go]"]
  node_linkify["Linkify<br/>[linkify.go]"]
  node_typographer["Typography<br/>[typographer.go]"]
  node_otherextensions["Other built-ins"]
end

node_caller(("Markdown caller"))
node_output(("Output writer"))

node_caller -->|"submits Markdown"| node_convert
node_convert -->|"creates reader"| node_reader
node_convert -->|"parses input"| node_parser
node_reader -->|"supplies text"| node_parser
node_parser -->|"builds AST"| node_ast
node_parser -->|"dispatches parsing"| node_blocksyntax
node_parser -->|"uses syntax"| node_links
node_parser -->|"uses syntax"| node_attributes
node_convert -->|"renders document"| node_renderer
node_renderer -->|"walks nodes"| node_ast
node_renderer -->|"registers renderer"| node_html
node_html -->|"renders nodes"| node_ast
node_convert -->|"writes result"| node_output
node_convert -->|"accepts extension"| node_gfm
node_gfm -.->|"enables feature"| node_tables
node_gfm -.->|"enables features"| node_otherextensions
node_tables -->|"adds transformer"| node_parser
node_tables -->|"builds table nodes"| node_ast
node_tables -->|"provides rendering"| node_html
node_footnotes -->|"adds parsers"| node_parser
node_footnotes -->|"provides rendering"| node_html
node_definitions -->|"adds parsing"| node_parser
node_linkify -->|"adds parsing"| node_parser
node_typographer -->|"adds transformer"| node_parser
node_otherextensions -.->|"adds features"| node_parser

click node_convert "https://github.com/krazybee/goldmark/blob/master/markdown.go"
click node_reader "https://github.com/krazybee/goldmark/blob/master/text/reader.go"
click node_parser "https://github.com/krazybee/goldmark/blob/master/parser/parser.go"
click node_blocksyntax "https://github.com/krazybee/goldmark/blob/master/parser/paragraph.go"
click node_links "https://github.com/krazybee/goldmark/blob/master/parser/link.go"
click node_attributes "https://github.com/krazybee/goldmark/blob/master/parser/attribute.go"
click node_ast "https://github.com/krazybee/goldmark/blob/master/ast/ast.go"
click node_renderer "https://github.com/krazybee/goldmark/blob/master/renderer/renderer.go"
click node_html "https://github.com/krazybee/goldmark/blob/master/renderer/html/html.go"
click node_gfm "https://github.com/krazybee/goldmark/blob/master/extension/gfm.go"
click node_tables "https://github.com/krazybee/goldmark/blob/master/extension/table.go"
click node_footnotes "https://github.com/krazybee/goldmark/blob/master/extension/footnote.go"
click node_definitions "https://github.com/krazybee/goldmark/blob/master/extension/definition_list.go"
click node_linkify "https://github.com/krazybee/goldmark/blob/master/extension/linkify.go"
click node_typographer "https://github.com/krazybee/goldmark/blob/master/extension/typographer.go"
click node_otherextensions "https://github.com/krazybee/goldmark/tree/master/extension"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_convert,node_reader toneBlue
class node_parser,node_blocksyntax,node_links,node_attributes,node_ast toneAmber
class node_renderer,node_html toneMint
class node_gfm,node_tables,node_footnotes,node_definitions,node_linkify,node_typographer,node_otherextensions toneRose
class node_caller,node_output toneIndigo
```

## Components

### Conversion Core

- [Conversion API](https://github.com/krazybee/goldmark/blob/master/markdown.go): `markdown.go`
- [Text reader](https://github.com/krazybee/goldmark/blob/master/text/reader.go): `text/reader.go`

### Parsing and AST

- [Parser engine](https://github.com/krazybee/goldmark/blob/master/parser/parser.go): `parser/parser.go`
- [Block syntax](https://github.com/krazybee/goldmark/blob/master/parser/paragraph.go): `parser/paragraph.go`
- [Links and delimiters](https://github.com/krazybee/goldmark/blob/master/parser/link.go): `parser/link.go`
- [Attributes](https://github.com/krazybee/goldmark/blob/master/parser/attribute.go): `parser/attribute.go`
- [Document AST](https://github.com/krazybee/goldmark/blob/master/ast/ast.go): `ast/ast.go`

### Rendering

- [Renderer engine](https://github.com/krazybee/goldmark/blob/master/renderer/renderer.go): `renderer/renderer.go`
- [HTML renderer](https://github.com/krazybee/goldmark/blob/master/renderer/html/html.go): `renderer/html/html.go`

### Markdown Extensions

- [GFM features](https://github.com/krazybee/goldmark/blob/master/extension/gfm.go): `extension/gfm.go`
- [Tables](https://github.com/krazybee/goldmark/blob/master/extension/table.go): `extension/table.go`
- [Footnotes](https://github.com/krazybee/goldmark/blob/master/extension/footnote.go): `extension/footnote.go`
- [Definition lists](https://github.com/krazybee/goldmark/blob/master/extension/definition_list.go): `extension/definition_list.go`
- [Linkify](https://github.com/krazybee/goldmark/blob/master/extension/linkify.go): `extension/linkify.go`
- [Typography](https://github.com/krazybee/goldmark/blob/master/extension/typographer.go): `extension/typographer.go`
- [Other built-ins](https://github.com/krazybee/goldmark/tree/master/extension): `extension`

### Other components

- **Markdown caller**
- **Output writer**

## Connections

- Markdown caller → Conversion API: submits Markdown
- Conversion API → Text reader: creates reader (evidence: `markdown.go`)
- Conversion API → Parser engine: parses input (evidence: `markdown.go`)
- Text reader → Parser engine: supplies text
- Parser engine → Document AST: builds AST (evidence: `parser/parser.go`)
- Parser engine → Block syntax: dispatches parsing (evidence: `parser/parser.go`)
- Parser engine → Links and delimiters: uses syntax (evidence: `parser/parser.go`)
- Parser engine → Attributes: uses syntax (evidence: `parser/parser.go`)
- Conversion API → Renderer engine: renders document (evidence: `markdown.go`)
- Renderer engine → Document AST: walks nodes (evidence: `renderer/renderer.go`)
- Renderer engine → HTML renderer: registers renderer
- HTML renderer → Document AST: renders nodes (evidence: `renderer/html/html.go`)
- Conversion API → Output writer: writes result (evidence: `markdown.go`)
- Conversion API → GFM features: accepts extension
- GFM features → Tables: enables feature
- GFM features → Other built-ins: enables features
- Tables → Parser engine: adds transformer (evidence: `extension/table.go`)
- Tables → Document AST: builds table nodes (evidence: `extension/table.go`)
- Tables → HTML renderer: provides rendering (evidence: `extension/table.go`)
- Footnotes → Parser engine: adds parsers (evidence: `extension/footnote.go`)
- Footnotes → HTML renderer: provides rendering (evidence: `extension/footnote.go`)
- Definition lists → Parser engine: adds parsing (evidence: `extension/definition_list.go`)
- Linkify → Parser engine: adds parsing (evidence: `extension/linkify.go`)
- Typography → Parser engine: adds transformer (evidence: `extension/typographer.go`)
- Other built-ins → Parser engine: adds features
