# github/markup architecture

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

- Interactive diagram: https://gitdiagram.com/github/markup
- Repository: https://github.com/github/markup

## Overview

1. **What this repo is**
   - `github-markup` is a Ruby gem that converts repository markup files into HTML.
   - Its scope is intentionally narrow: it only performs the “raw markup → HTML” conversion step. Sanitization, syntax highlighting, emoji, task lists, and other GitHub.com rendering steps are outside this repo.

2. **Primary entrypoint**
   - The public API is centered in `lib/github/markup.rb` and exposed through `require 'github/markup'`.
   - The main usage pattern is: provide a filename plus content, and the library chooses the correct renderer based on the file extension.

3. **Markup type registry**
   - `lib/github/markups.rb` acts as the registry of supported formats and their file extensions.
   - This is the routing layer for the whole gem: it maps extensions like `.md`, `.rst`, `.pod`, `.asciidoc`, `.textile`, etc. to the right implementation.

4. **Implementation abstraction**
   - `lib/github/markup/implementation.rb` defines the common contract for renderers.
   - The architecture is pluggable: each markup format is represented as an implementation object rather than hardcoded branching scattered through the codebase.

5. **Two implementation styles**
   - `lib/github/markup/gem_implementation.rb` covers markups rendered through Ruby gems or in-process libraries.
   - `lib/github/markup/command_implementation.rb` covers markups rendered by shelling out to external commands or interpreters.
   - This split is important for the architecture: some formats are native Ruby dependencies, while others depend on system tools such as Python, Perl, or standalone CLI utilities.

6. **Format-specific adapters**
   - `lib/github/markup/markdown.rb` and `lib/github/markup/rdoc.rb` are format-specific wrappers for special cases that need custom behavior.
   - These adapters sit above the generic implementation layer and handle format quirks without changing the registry or API shape.

7. **Executable/rendering bridge**
   - `bin/github-markup` is the command-line entrypoint for converting files from the shell.
   - The `lib/github/commands/` directory contains helper command wrappers such as `pod2html`, `pod62html`, and `rest2html`, which are used to bridge to external format converters.

8. **External rendering dependencies**
   - Supported markups depend on a mix of libraries and tools: `commonmarker`, `RedCloth`, `rdoc`, `org-ruby`, `creole`, `wikicloth`, `docutils`, `asciidoctor`, and Perl `Pod::Simple`.
   - In architecture terms, the gem is a dispatcher that delegates rendering to these downstream engines rather than implementing the markup parsers itself.

9. **Data flow through the library**
   - Input begins as a filename plus raw text.
   - The filename determines the markup type.
   - The selected implementation converts the text to HTML.
   - The caller receives HTML and is expected to handle any downstream sanitization or display concerns.

10. **Test strategy**
   - `test/markups/` contains paired source and expected HTML fixtures for each supported syntax.
   - `test/markup_test.rb` and `test/coverage_test.rb` validate the registry, dispatch behavior, and renderer coverage across all supported formats.
   - The fixture-heavy layout suggests the repo’s main correctness concern is parity across many converters.

11. **Development and automation**
   - `script/bootstrap` and `script/cibuild` support local dependency setup and CI execution.
   - GitHub Actions in `.github/workflows/ci.yml` and `.github/workflows/stale.yml` handle automated testing and repository maintenance.
   - Dependabot configuration indicates dependency updates are part of the operational model.

12. **How to draw the architecture**
   - A good diagram would show:
     - a public API / CLI boundary,
     - a format registry,
     - a shared implementation abstraction,
     - multiple concrete renderer adapters,
     - and a set of external parser/converter dependencies behind those adapters.
   - The key architectural idea is dispatch-by-file-extension into heterogeneous rendering backends.

Main entry points: [`lib/github/markup/gem_implementation.rb`](https://github.com/github/markup/blob/master/lib/github/markup/gem_implementation.rb) (Gem adapter), [`lib/github/markup/implementation.rb`](https://github.com/github/markup/blob/master/lib/github/markup/implementation.rb) (Impl contract), [`lib/github/markups.rb`](https://github.com/github/markup/blob/master/lib/github/markups.rb) (Markup registry), [`test/markup_test.rb`](https://github.com/github/markup/blob/master/test/markup_test.rb) (Markup tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Public entrypoints"]
  node_n1["Library API<br/>Ruby entrypoint<br/>[markup.rb]"]
  node_n2["CLI tool<br/>Shell entrypoint"]
end

subgraph group_g2["Dispatch core"]
  node_n3[("Markup registry<br/>Extension router<br/>[markups.rb]")]
  node_n4["Impl contract<br/>Renderer interface<br/>[implementation.rb]"]
end

subgraph group_g3["Renderer adapters"]
  node_n5["Gem adapter<br/>In-process backend"]
  node_n6["Command adapter<br/>External backend"]
  node_n7["Markdown wrapper<br/>Format adapter<br/>[markdown.rb]"]
  node_n8["RDoc wrapper<br/>Format adapter<br/>[rdoc.rb]"]
  node_n17["POD helpers<br/>Command bridge"]
  node_n18["RST helper<br/>Command bridge"]
end

subgraph group_g4["External engines"]
  node_n9["CommonMarker<br/>Ruby gem"]
  node_n10["RedCloth<br/>Ruby gem"]
  node_n11["RDoc<br/>Ruby stdlib"]
  node_n12["Org/Creole<br/>Ruby gems"]
  node_n13["Wiki/MediaWiki<br/>Ruby gems"]
  node_n14["Docutils<br/>Python tool"]
  node_n15["AsciiDoctor<br/>Ruby gem"]
  node_n16["Pod::Simple<br/>Perl module"]
end

subgraph group_g5["Verification"]
  node_n19["Markup tests<br/>Fixture suite<br/>[markup_test.rb]"]
  node_n20["Coverage tests<br/>Coverage suite<br/>[coverage_test.rb]"]
  node_n21["Markup fixtures<br/>Golden files"]
end

subgraph group_g6["Automation"]
  node_n22["Build scripts<br/>Dev scripts"]
  node_n23["CI config<br/>Workflow config<br/>[ci.yml]"]
end

node_n1 -->|"dispatches by extension"| node_n3
node_n2 -->|"uses API"| node_n1
node_n3 -->|"selects impls"| node_n4
node_n7 -->|"specializes"| node_n5
node_n8 -->|"specializes"| node_n4
node_n5 -->|"delegates to"| node_n9
node_n5 -->|"delegates to"| node_n10
node_n5 -->|"delegates to"| node_n11
node_n5 -->|"delegates to"| node_n12
node_n5 -->|"delegates to"| node_n13
node_n5 -->|"delegates to"| node_n15
node_n6 -->|"spawns"| node_n14
node_n17 -->|"bridges to"| node_n16
node_n18 -->|"bridges to"| node_n14
node_n4 -->|"implemented by"| node_n5
node_n4 -->|"implemented by"| node_n6
node_n19 -->|"validates"| node_n3
node_n19 -->|"uses fixtures"| node_n21
node_n20 -->|"covers"| node_n3
node_n22 -->|"feeds"| node_n23
node_n23 -->|"runs"| node_n19

click node_n1 "https://github.com/github/markup/blob/master/lib/github/markup.rb"
click node_n2 "https://github.com/github/markup/tree/master/bin/github-markup"
click node_n3 "https://github.com/github/markup/blob/master/lib/github/markups.rb"
click node_n4 "https://github.com/github/markup/blob/master/lib/github/markup/implementation.rb"
click node_n5 "https://github.com/github/markup/blob/master/lib/github/markup/gem_implementation.rb"
click node_n6 "https://github.com/github/markup/blob/master/lib/github/markup/command_implementation.rb"
click node_n7 "https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb"
click node_n8 "https://github.com/github/markup/blob/master/lib/github/markup/rdoc.rb"
click node_n17 "https://github.com/github/markup/tree/master/lib/github/commands/pod2html"
click node_n18 "https://github.com/github/markup/tree/master/lib/github/commands/rest2html"
click node_n19 "https://github.com/github/markup/blob/master/test/markup_test.rb"
click node_n20 "https://github.com/github/markup/blob/master/test/coverage_test.rb"
click node_n21 "https://github.com/github/markup/tree/master/test/markups"
click node_n22 "https://github.com/github/markup/tree/master/script/bootstrap"
click node_n23 "https://github.com/github/markup/blob/master/.github/workflows/ci.yml"

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_n1,node_n2 toneBlue
class node_n3,node_n4 toneAmber
class node_n5,node_n6,node_n7,node_n8,node_n17,node_n18 toneMint
class node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16 toneRose
class node_n19,node_n20,node_n21 toneIndigo
class node_n22,node_n23 toneTeal
```

## Components

### Public entrypoints

User-facing Ruby and CLI boundaries for conversion.

- [Library API](https://github.com/github/markup/blob/master/lib/github/markup.rb): Ruby entrypoint · Main require path and public conversion API. · `lib/github/markup.rb`
- [CLI tool](https://github.com/github/markup/tree/master/bin/github-markup): Shell entrypoint · Command-line interface for converting files from the shell. · `bin/github-markup`

### Dispatch core

Registry and implementation abstraction that route markup to backends.

- [Markup registry](https://github.com/github/markup/blob/master/lib/github/markups.rb): Extension router · Maps filename extensions to supported markup implementations. · `lib/github/markups.rb`
- [Impl contract](https://github.com/github/markup/blob/master/lib/github/markup/implementation.rb): Renderer interface · Common abstraction shared by all renderers. · `lib/github/markup/implementation.rb`

### Renderer adapters

Format-specific wrappers and backend families used by the dispatcher.

- [Gem adapter](https://github.com/github/markup/blob/master/lib/github/markup/gem_implementation.rb): In-process backend · Implementation path for Ruby gems and libraries. · `lib/github/markup/gem_implementation.rb`
- [Command adapter](https://github.com/github/markup/blob/master/lib/github/markup/command_implementation.rb): External backend · Implementation path for shelling out to external tools. · `lib/github/markup/command_implementation.rb`
- [Markdown wrapper](https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb): Format adapter · Custom behavior for markdown-family rendering. · `lib/github/markup/markdown.rb`
- [RDoc wrapper](https://github.com/github/markup/blob/master/lib/github/markup/rdoc.rb): Format adapter · Custom behavior for RDoc-family rendering. · `lib/github/markup/rdoc.rb`
- [POD helpers](https://github.com/github/markup/tree/master/lib/github/commands/pod2html): Command bridge · Helper wrappers for pod-to-html conversion. · `lib/github/commands/pod2html`
- [RST helper](https://github.com/github/markup/tree/master/lib/github/commands/rest2html): Command bridge · Helper wrapper for reStructuredText conversion. · `lib/github/commands/rest2html`

### External engines

Native gems, interpreters, and commands that perform actual markup conversion.

- **CommonMarker**: Ruby gem · Markdown engine used for modern Markdown conversion.
- **RedCloth**: Ruby gem · Textile rendering library.
- **RDoc**: Ruby stdlib · RDoc parser and formatter used for documentation markup.
- **Org/Creole**: Ruby gems · In-process support for Org mode and Creole-like formats.
- **Wiki/MediaWiki**: Ruby gems · Wiki-style converters such as Wikicloth.
- **Docutils**: Python tool · External reStructuredText converter.
- **AsciiDoctor**: Ruby gem · AsciiDoc rendering engine.
- **Pod::Simple**: Perl module · Perl POD converter used through command wrappers.

### Verification

Fixture-driven tests that validate dispatch and renderer coverage.

- [Markup tests](https://github.com/github/markup/blob/master/test/markup_test.rb): Fixture suite · Registry and dispatch tests across supported formats. · `test/markup_test.rb`
- [Coverage tests](https://github.com/github/markup/blob/master/test/coverage_test.rb): Coverage suite · Checks renderer coverage against supported markups. · `test/coverage_test.rb`
- [Markup fixtures](https://github.com/github/markup/tree/master/test/markups): Golden files · Paired source and expected HTML fixtures for each syntax. · `test/markups`

### Automation

Local scripts and CI/maintenance configuration.

- [Build scripts](https://github.com/github/markup/tree/master/script/bootstrap): Dev scripts · Bootstrap and CI helper scripts for local and automated runs. · `script/bootstrap`
- [CI config](https://github.com/github/markup/blob/master/.github/workflows/ci.yml): Workflow config · GitHub Actions workflows and dependency automation. · `.github/workflows/ci.yml`

## Connections

- Library API → Markup registry: dispatches by extension · The public API delegates filename-based routing to the registry.
- CLI tool → Library API: uses API · CLI entrypoint invokes the library conversion flow.
- Markup registry → Impl contract: selects impls · Registry entries resolve to implementation objects.
- Markdown wrapper → Gem adapter: specializes · Markdown-specific wrapper builds on the gem implementation path.
- RDoc wrapper → Impl contract: specializes · RDoc wrapper customizes behavior over the shared contract.
- Gem adapter → CommonMarker: delegates to · Gem-backed renderer uses CommonMarker for markdown.
- Gem adapter → RedCloth: delegates to · Gem-backed renderer uses RedCloth for textile.
- Gem adapter → RDoc: delegates to · Gem-backed renderer uses RDoc for documentation markup.
- Gem adapter → Org/Creole: delegates to · Gem-backed renderer uses org/creole libraries for alternate syntaxes.
- Gem adapter → Wiki/MediaWiki: delegates to · Gem-backed renderer uses wiki-style libraries for wiki markups.
- Gem adapter → AsciiDoctor: delegates to · Gem-backed renderer uses AsciiDoctor for AsciiDoc.
- Command adapter → Docutils: spawns · Command-backed renderer shells out to docutils for reStructuredText.
- POD helpers → Pod::Simple: bridges to · POD helper wraps Perl POD conversion tooling.
- RST helper → Docutils: bridges to · RST helper wraps external docutils-based conversion.
- Impl contract → Gem adapter: implemented by · One major renderer family is in-process Ruby libraries.
- Impl contract → Command adapter: implemented by · One major renderer family shells out to external commands.
- Markup tests → Markup registry: validates · Tests assert registry mappings and dispatch behavior.
- Markup tests → Markup fixtures: uses fixtures · Behavior is verified against paired source/HTML samples.
- Coverage tests → Markup registry: covers · Coverage tests ensure supported formats are exercised.
- Build scripts → CI config: feeds · Local scripts support CI and automation workflows.
- CI config → Markup tests: runs · CI executes the main test suite.
