# rktim/markd architecture

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

- Interactive diagram: https://gitdiagram.com/rktim/markd
- Repository: https://github.com/rktim/markd
- Video tour (about a minute): https://gitdiagram.com/rktim/markd/video

## Overview

markd is a terminal document viewer. The workflow parses a file argument, loads Markdown directly or converts other formats through MarkItDown, then either prints the resulting text or opens an interactive viewer. The TUI supports scrolling, resizing, mouse and keyboard theme selection, and themed rendering. Conversion may locate an existing MarkItDown executable or provision one in a private Python environment. The README documents PDF, Word, Excel, and PowerPoint support. TUI internals are only partially sampled, so the graph omits uncertain rendering details.

Main entry points: [`src/main.rs`](https://github.com/rktim/markd/blob/main/src/main.rs) (Application entry), [`src/document.rs`](https://github.com/rktim/markd/blob/main/src/document.rs) (Document loader), [`src/tui.rs`](https://github.com/rktim/markd/blob/main/src/tui.rs) (TUI controller), [`src/cli.rs`](https://github.com/rktim/markd/blob/main/src/cli.rs) (Argument parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and output"]
  node_main["Application entry<br/>[main.rs]"]
  node_cli["Argument parsing<br/>[cli.rs]"]
  node_print["Print output<br/>[document.rs]"]
end

subgraph group_documents["Document handling"]
  node_loader["Document loader<br/>[document.rs]"]
  node_markdown["Markdown reader<br/>[document.rs]"]
  node_installer["MarkItDown setup<br/>[document.rs]"]
  node_document["Loaded content<br/>[document.rs]"]
end

subgraph group_viewer["Interactive viewer"]
  node_tui["TUI controller<br/>[tui.rs]"]
  node_theme["Theme definitions<br/>[theme.rs]"]
  node_renderer["Terminal rendering<br/>[tui.rs]"]
end

node_user(("User"))
node_terminal(("Terminal"))
node_docfile["Input document"]
node_environment["Python environment"]
node_converter["MarkItDown converter"]

node_user -->|"provides arguments"| node_cli
node_cli -->|"returns options"| node_main
node_main -->|"loads file"| node_loader
node_docfile -->|"reads input"| node_loader
node_loader -->|"reads Markdown"| node_markdown
node_loader -->|"ensures converter"| node_installer
node_installer -->|"provisions if needed"| node_environment
node_installer -->|"locates executable"| node_converter
node_markdown -->|"returns content"| node_document
node_converter -->|"returns converted text"| node_document
node_main -->|"prints in print mode"| node_print
node_main -->|"starts viewer"| node_tui
node_document -->|"supplies content"| node_print
node_document -->|"supplies content"| node_tui
node_tui -->|"selects theme"| node_theme
node_tui -->|"renders interface"| node_renderer
node_theme -->|"provides styles"| node_renderer
node_renderer -->|"writes display"| node_terminal
node_user -->|"uses controls"| node_terminal

click node_main "https://github.com/rktim/markd/blob/main/src/main.rs"
click node_cli "https://github.com/rktim/markd/blob/main/src/cli.rs"
click node_print "https://github.com/rktim/markd/blob/main/src/document.rs"
click node_loader "https://github.com/rktim/markd/blob/main/src/document.rs"
click node_markdown "https://github.com/rktim/markd/blob/main/src/document.rs"
click node_installer "https://github.com/rktim/markd/blob/main/src/document.rs"
click node_document "https://github.com/rktim/markd/blob/main/src/document.rs"
click node_tui "https://github.com/rktim/markd/blob/main/src/tui.rs"
click node_theme "https://github.com/rktim/markd/blob/main/src/theme.rs"
click node_renderer "https://github.com/rktim/markd/blob/main/src/tui.rs"

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_main,node_cli,node_print,node_user toneBlue
class node_loader,node_markdown,node_installer,node_document toneAmber
class node_tui,node_theme,node_renderer toneMint
class node_terminal,node_docfile,node_environment,node_converter toneIndigo
```

## Components

### Entry and output

- [Application entry](https://github.com/rktim/markd/blob/main/src/main.rs): `src/main.rs`
- [Argument parsing](https://github.com/rktim/markd/blob/main/src/cli.rs): `src/cli.rs`
- [Print output](https://github.com/rktim/markd/blob/main/src/document.rs): `src/document.rs`

### Document handling

- [Document loader](https://github.com/rktim/markd/blob/main/src/document.rs): `src/document.rs`
- [Markdown reader](https://github.com/rktim/markd/blob/main/src/document.rs): `src/document.rs`
- [MarkItDown setup](https://github.com/rktim/markd/blob/main/src/document.rs): `src/document.rs`
- [Loaded content](https://github.com/rktim/markd/blob/main/src/document.rs): `src/document.rs`

### Interactive viewer

- [TUI controller](https://github.com/rktim/markd/blob/main/src/tui.rs): `src/tui.rs`
- [Theme definitions](https://github.com/rktim/markd/blob/main/src/theme.rs): `src/theme.rs`
- [Terminal rendering](https://github.com/rktim/markd/blob/main/src/tui.rs): `src/tui.rs`

### Other components

- **User**
- **Terminal**
- **Input document**
- **Python environment**
- **MarkItDown converter**

## Connections

- User → Argument parsing: provides arguments
- Argument parsing → Application entry: returns options
- Application entry → Document loader: loads file
- Input document → Document loader: reads input
- Document loader → Markdown reader: reads Markdown
- Document loader → MarkItDown setup: ensures converter
- MarkItDown setup → Python environment: provisions if needed
- MarkItDown setup → MarkItDown converter: locates executable
- Markdown reader → Loaded content: returns content
- MarkItDown converter → Loaded content: returns converted text
- Application entry → Print output: prints in print mode
- Application entry → TUI controller: starts viewer
- Loaded content → Print output: supplies content
- Loaded content → TUI controller: supplies content
- TUI controller → Theme definitions: selects theme
- TUI controller → Terminal rendering: renders interface
- Theme definitions → Terminal rendering: provides styles
- Terminal rendering → Terminal: writes display
- User → Terminal: uses controls