# johanneskaufmann/html-to-markdown architecture

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

- Interactive diagram: https://gitdiagram.com/johanneskaufmann/html-to-markdown
- Repository: https://github.com/johanneskaufmann/html-to-markdown

## Overview

html-to-markdown converts parsed HTML into Markdown through a configurable Go converter, with a library wrapper and a CLI path for input selection, optional plugins, and output. The core stages are parsing/filtering, plugin-driven rendering, and output formatting; shared collapse and escaping utilities support rendering. The README also describes custom tag renderers, CommonMark options, strikethrough, and tables. Edges reflect the supplied excerpts or explicit README usage; unsampled CLI I/O and converter internals are not expanded into guessed calls.

Main entry points: [`cli/html2markdown/cmd/cmd_convert.go`](https://github.com/johanneskaufmann/html-to-markdown/blob/main/cli/html2markdown/cmd/cmd_convert.go) (CLI command), [`plugin/base/base.go`](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/base/base.go) (Base cleanup), [`plugin/commonmark/commonmark.go`](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/commonmark.go) (CommonMark syntax), [`convert.go`](https://github.com/johanneskaufmann/html-to-markdown/blob/main/convert.go) (Go library API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_library["Go library API<br/>[convert.go]"]
  node_cli["CLI command<br/>[cmd_convert.go]"]
  node_cli_main["CLI executable<br/>[main.go]"]
end

subgraph group_engine["Conversion engine"]
  node_converter["Converter runtime<br/>[convert.go]"]
  node_registration["Plugin registration<br/>[register.go]"]
  node_tag_rendering["Tag render registry<br/>[register.go]"]
end

subgraph group_plugins["Rendering plugins"]
  node_base["Base cleanup<br/>[base.go]"]
  node_base_renderers["HTML wrappers<br/>[renderers.go]"]
  node_commonmark["CommonMark syntax<br/>[commonmark.go]"]
  node_code["Code rendering<br/>[render_code.go]"]
  node_headings["Heading rendering<br/>[render_heading.go]"]
  node_strikethrough["Strikethrough<br/>[strikethrough.go]"]
  node_table_setup["Table plugin<br/>[table.go]"]
  node_table_collect["Table collection<br/>[2_collect.go]"]
  node_table_render["Table formatting<br/>[3_render.go]"]
end

subgraph group_shared["Shared processing"]
  node_collapse["Whitespace collapse<br/>[collapse.go]"]
  node_domutils["DOM helpers"]
  node_textutils["Text helpers"]
  node_escape["Markdown escaping"]
end

node_input_user(("Library caller"))
node_cli_user(("CLI user"))
node_markdown["Markdown output"]

node_input_user -->|"provides HTML"| node_library
node_library -->|"constructs and converts"| node_converter
node_cli_user -->|"invokes"| node_cli_main
node_cli_main -->|"calls Run"| node_cli
node_cli -->|"parses and converts"| node_converter
node_cli -->|"registers"| node_base
node_cli -->|"registers"| node_commonmark
node_cli -->|"optionally registers"| node_strikethrough
node_cli -->|"optionally registers"| node_table_setup
node_library -->|"registers"| node_base
node_library -->|"registers"| node_commonmark
node_converter -.->|"uses"| node_registration
node_registration -.->|"configures"| node_tag_rendering
node_base -->|"collapses whitespace"| node_collapse
node_base -->|"merges text nodes"| node_domutils
node_base -->|"trims output"| node_textutils
node_base -.->|"escapes content"| node_escape
node_commonmark -->|"normalizes lists"| node_domutils
node_commonmark -->|"registers unescapers"| node_escape
node_commonmark -.->|"delegates code syntax"| node_code
node_commonmark -.->|"delegates headings"| node_headings
node_base_renderers -->|"provides renderers"| node_tag_rendering
node_strikethrough -->|"normalizes elements"| node_domutils
node_strikethrough -->|"wraps multiline text"| node_textutils
node_table_setup -->|"collects cell content"| node_table_collect
node_table_setup -.->|"renders table output"| node_table_render
node_table_collect -->|"renders cell nodes"| node_textutils
node_converter -.->|"returns Markdown"| node_markdown
node_library -->|"returns Markdown"| node_markdown
node_cli -->|"returns Markdown"| node_markdown

click node_library "https://github.com/johanneskaufmann/html-to-markdown/blob/main/convert.go"
click node_cli "https://github.com/johanneskaufmann/html-to-markdown/blob/main/cli/html2markdown/cmd/cmd_convert.go"
click node_cli_main "https://github.com/johanneskaufmann/html-to-markdown/blob/main/cli/html2markdown/main.go"
click node_converter "https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/convert.go"
click node_registration "https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/register.go"
click node_tag_rendering "https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/register.go"
click node_base "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/base/base.go"
click node_base_renderers "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/base/renderers.go"
click node_commonmark "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/commonmark.go"
click node_code "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/render_code.go"
click node_headings "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/render_heading.go"
click node_strikethrough "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/strikethrough/strikethrough.go"
click node_table_setup "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/table.go"
click node_table_collect "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/2_collect.go"
click node_table_render "https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/3_render.go"
click node_collapse "https://github.com/johanneskaufmann/html-to-markdown/blob/main/collapse/collapse.go"
click node_domutils "https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/domutils"
click node_textutils "https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/textutils"
click node_escape "https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/escape"

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_library,node_cli,node_cli_main,node_cli_user toneBlue
class node_converter,node_registration,node_tag_rendering toneAmber
class node_base,node_base_renderers,node_commonmark,node_code,node_headings,node_strikethrough,node_table_setup,node_table_collect,node_table_render toneMint
class node_collapse,node_domutils,node_textutils,node_escape toneRose
class node_input_user,node_markdown toneIndigo
```

## Components

### Entry points

- [Go library API](https://github.com/johanneskaufmann/html-to-markdown/blob/main/convert.go): `convert.go`
- [CLI command](https://github.com/johanneskaufmann/html-to-markdown/blob/main/cli/html2markdown/cmd/cmd_convert.go): `cli/html2markdown/cmd/cmd_convert.go`
- [CLI executable](https://github.com/johanneskaufmann/html-to-markdown/blob/main/cli/html2markdown/main.go): `cli/html2markdown/main.go`

### Conversion engine

- [Converter runtime](https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/convert.go): `converter/convert.go`
- [Plugin registration](https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/register.go): `converter/register.go`
- [Tag render registry](https://github.com/johanneskaufmann/html-to-markdown/blob/main/converter/register.go): `converter/register.go`

### Rendering plugins

- [Base cleanup](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/base/base.go): `plugin/base/base.go`
- [HTML wrappers](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/base/renderers.go): `plugin/base/renderers.go`
- [CommonMark syntax](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/commonmark.go): `plugin/commonmark/commonmark.go`
- [Code rendering](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/render_code.go): `plugin/commonmark/render_code.go`
- [Heading rendering](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/commonmark/render_heading.go): `plugin/commonmark/render_heading.go`
- [Strikethrough](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/strikethrough/strikethrough.go): `plugin/strikethrough/strikethrough.go`
- [Table plugin](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/table.go): `plugin/table/table.go`
- [Table collection](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/2_collect.go): `plugin/table/2_collect.go`
- [Table formatting](https://github.com/johanneskaufmann/html-to-markdown/blob/main/plugin/table/3_render.go): `plugin/table/3_render.go`

### Shared processing

- [Whitespace collapse](https://github.com/johanneskaufmann/html-to-markdown/blob/main/collapse/collapse.go): `collapse/collapse.go`
- [DOM helpers](https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/domutils): `internal/domutils`
- [Text helpers](https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/textutils): `internal/textutils`
- [Markdown escaping](https://github.com/johanneskaufmann/html-to-markdown/tree/main/internal/escape): `internal/escape`

### Other components

- **Library caller**
- **CLI user**
- **Markdown output**

## Connections

- Library caller → Go library API: provides HTML (evidence: `convert.go`)
- Go library API → Converter runtime: constructs and converts (evidence: `convert.go`)
- CLI user → CLI executable: invokes (evidence: `cli/html2markdown/main.go`)
- CLI executable → CLI command: calls Run (evidence: `cli/html2markdown/main.go`)
- CLI command → Converter runtime: parses and converts (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
- CLI command → Base cleanup: registers (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
- CLI command → CommonMark syntax: registers (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
- CLI command → Strikethrough: optionally registers (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
- CLI command → Table plugin: optionally registers (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
- Go library API → Base cleanup: registers (evidence: `convert.go`)
- Go library API → CommonMark syntax: registers (evidence: `convert.go`)
- Converter runtime → Plugin registration: uses
- Plugin registration → Tag render registry: configures (evidence: `converter/register.go`)
- Base cleanup → Whitespace collapse: collapses whitespace (evidence: `plugin/base/base.go`)
- Base cleanup → DOM helpers: merges text nodes (evidence: `plugin/base/base.go`)
- Base cleanup → Text helpers: trims output (evidence: `plugin/base/base.go`)
- Base cleanup → Markdown escaping: escapes content
- CommonMark syntax → DOM helpers: normalizes lists (evidence: `plugin/commonmark/commonmark.go`)
- CommonMark syntax → Markdown escaping: registers unescapers (evidence: `plugin/commonmark/commonmark.go`)
- CommonMark syntax → Code rendering: delegates code syntax
- CommonMark syntax → Heading rendering: delegates headings
- HTML wrappers → Tag render registry: provides renderers (evidence: `plugin/base/renderers.go`)
- Strikethrough → DOM helpers: normalizes elements (evidence: `plugin/strikethrough/strikethrough.go`)
- Strikethrough → Text helpers: wraps multiline text (evidence: `plugin/strikethrough/strikethrough.go`)
- Table plugin → Table collection: collects cell content (evidence: `plugin/table/2_collect.go`)
- Table plugin → Table formatting: renders table output
- Table collection → Text helpers: renders cell nodes (evidence: `plugin/table/2_collect.go`)
- Converter runtime → Markdown output: returns Markdown
- Go library API → Markdown output: returns Markdown (evidence: `convert.go`)
- CLI command → Markdown output: returns Markdown (evidence: `cli/html2markdown/cmd/cmd_convert.go`)
