# dead8309/markitdown-ts architecture

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

- Interactive diagram: https://gitdiagram.com/dead8309/markitdown-ts
- Repository: https://github.com/dead8309/markitdown-ts

## Overview

1. **What this repo is**
   - `markitdown-ts` is a TypeScript conversion library, not an app.
   - Its core job is to turn many input formats into a single Markdown-oriented output shape: `{ title, markdown, text_content }`.
   - The repository is organized as a library package plus a set of example mini-projects and a test suite.

2. **Public entrypoint and orchestration**
   - `src/index.ts` exposes the library API, centered on the `MarkItDown` class defined in `src/markitdown.ts`.
   - `MarkItDown` is the orchestration layer: it accepts a source, selects the right converter, and returns a normalized result or `null/undefined` when conversion cannot be performed.
   - The two main input modes are `convert(source)` for path/URL/Response and `convertBuffer(source, { file_extension })` for in-memory data.

3. **Source ingestion boundary**
   - The library is built around multiple source types: local file paths, remote URLs, `Response` objects, and raw `Buffer`s.
   - That boundary matters architecturally because the same converter logic is reused across filesystem, network, and serverless/edge scenarios.
   - The README explicitly positions this for environments without persistent disks, and `fetch` can be overridden for custom runtimes.

4. **Converter subsystem**
   - `src/converters/` contains the format-specific adapters, which are the main internal subsystem.
   - Each file in that folder handles one content family: PDF, DOCX, XLSX, HTML, plain text, XML/RSS/Atom, IPYNB, image, audio/WAV/MP3, ZIP, YouTube, Wikipedia, and Bing SERP.
   - The architecture is “dispatch to specialized converter,” not “one generic parser.”

5. **Document and text-oriented conversions**
   - Document formats are handled by dedicated converters for `pdf`, `docx`, `xlsx`, `ipynb`, and text-based formats.
   - The `html` converter likely depends on the custom Turndown layer in `src/custom-turndown.ts` to turn HTML into Markdown with project-specific rules.
   - `plain-text.ts` and `xml-rss-atom.ts` cover simple textual sources, while `bingserp.ts` and `wikipedia.ts` are URL/document hybrids that use page structure rather than file extension alone.

6. **Media and enrichment paths**
   - `image.ts`, `mp3.ts`, and `wav.ts` represent media-specific branches.
   - Image conversion supports optional LLM-based description generation, which introduces an external model/client dependency into an otherwise local conversion pipeline.
   - Audio conversion currently appears metadata-only in practice, with speech recognition explicitly not implemented yet in the README.

7. **Network-dependent converters**
   - Some converters are inherently remote or URL-driven: YouTube transcript extraction, Wikipedia page conversion, and Bing SERP parsing.
   - These paths depend on network access and/or page-specific structure, so they are separate from pure file parsing.
   - The YouTube path has an explicit feature flag for transcript extraction plus a language option, making transcript retrieval an optional enrichment step.

8. **Archive handling and recursion**
   - `zip.ts` is a special boundary because it recursively iterates over extracted contents instead of treating the archive as a single document.
   - The `cleanupExtracted` option in the API shows that ZIP conversion has lifecycle concerns around temporary extraction artifacts.
   - This is the main “composite input” path in the repo: one conversion request can fan out into many nested conversions.

9. **Shared types and implementation support**
   - `src/types.ts` centralizes the shared option/result shapes used across converters.
   - `src/declarations.d.ts` indicates the library needs local type declarations for some dependencies or runtime APIs.
   - This shared layer helps keep the many converters consistent while still allowing format-specific options like `styleMap`, `url`, `llmModel`, and transcript settings.

10. **Examples as executable documentation**
   - `examples/` contains one self-contained package per supported scenario, each with its own `src/index.ts`, `package.json`, and TypeScript config.
   - These are not just docs; they show the intended integration style for each converter family, including local files, URLs, and sample assets.
   - The examples also reveal the repo’s supported inputs and serve as reference integration boundaries for consumers.

11. **Testing and fixture strategy**
   - `test/index.test.ts` drives automated verification using representative files in `test/__files`.
   - The fixture set mirrors the supported converter matrix: PDF, DOCX, XLSX, HTML, ZIP, notebooks, WAV, TXT, XML/RSS, SERP, Wikipedia, and more.
   - This suggests the test architecture is conversion-result based, with format fixtures acting as the main dependency boundary.

12. **Build, CI, and release flow**
   - The repo uses pnpm workspaces (`pnpm-workspace.yaml`) and TypeScript configuration at the root and per-example level.
   - GitHub Actions (`.github/workflows/ci.yml`, `release.yml`) handle validation and publishing/release automation.
   - `build.config.ts` and Renovate config indicate standard library packaging and dependency maintenance rather than application runtime infrastructure.

13. **How to draw the main architecture**
   - The simplest diagram is: consumer input → `MarkItDown` orchestration → source normalization/fetching → format-specific converter → Markdown result.
   - Add side branches for optional external services: LLM-backed image descriptions, YouTube transcript retrieval, and network-driven page converters.
   - Add a composite branch for ZIP archives that loops back into the same converter pipeline for nested files.

Main entry points: [`src/converters`](https://github.com/dead8309/markitdown-ts/tree/main/src/converters) (Converters), [`.github/workflows/ci.yml`](https://github.com/dead8309/markitdown-ts/blob/main/.github/workflows/ci.yml) (Build/CI), [`src/markitdown.ts`](https://github.com/dead8309/markitdown-ts/blob/main/src/markitdown.ts) (MarkItDown), [`src/types.ts`](https://github.com/dead8309/markitdown-ts/blob/main/src/types.ts) (Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["src"]
  node_node_entry["API entry<br/>public surface<br/>[index.ts]"]
  node_node_markitdown["MarkItDown<br/>orchestrator<br/>[markitdown.ts]"]
  node_node_types["Types<br/>shared schema<br/>[types.ts]"]
  node_node_decls["Decls<br/>type shims<br/>[declarations.d.ts]"]
  node_node_turndown["Turndown<br/>html rules<br/>[custom-turndown.ts]"]
  node_node_dispatch["Converters<br/>adapter set"]
  node_node_files[("Files<br/>local/remote source")]
  node_node_pdf["PDF<br/>document converter<br/>[pdf.ts]"]
  node_node_docx["DOCX<br/>document converter<br/>[docx.ts]"]
  node_node_xlsx["XLSX<br/>spreadsheet converter<br/>[xlsx.ts]"]
  node_node_html["HTML<br/>markup converter<br/>[html.ts]"]
  node_node_textxml["Text/XML<br/>text converters<br/>[plain-text.ts]"]
  node_node_media["Media<br/>[media.ts]"]
  node_node_image["Image<br/>[image.ts]"]
  node_node_audio["Audio<br/>[wav.ts]"]
  node_node_youtube["YouTube<br/>network converter<br/>[youtube.ts]"]
  node_node_wiki["Wikipedia<br/>network converter<br/>[wikipedia.ts]"]
  node_node_serp["Bing SERP<br/>network converter<br/>[bingserp.ts]"]
  node_node_zip["ZIP<br/>archive converter<br/>[zip.ts]"]
end

subgraph group_group_examples["examples"]
  node_node_examples["Examples<br/>example packages"]
end

subgraph group_group_test["test"]
  node_node_tests["Tests<br/>fixture suite<br/>[index.test.ts]"]
end

subgraph group_group_ci["ci"]
  node_node_ci["Build/CI<br/>automation<br/>[ci.yml]"]
end

node_node_entry -->|"exports"| node_node_markitdown
node_node_markitdown -->|"ingests"| node_node_files
node_node_markitdown -->|"dispatches"| node_node_dispatch
node_node_markitdown -->|"returns"| node_node_types
node_node_dispatch -->|"includes"| node_node_pdf
node_node_dispatch -->|"includes"| node_node_docx
node_node_dispatch -->|"includes"| node_node_xlsx
node_node_dispatch -->|"includes"| node_node_html
node_node_dispatch -->|"includes"| node_node_textxml
node_node_dispatch -->|"includes"| node_node_media
node_node_dispatch -->|"includes"| node_node_youtube
node_node_dispatch -->|"includes"| node_node_wiki
node_node_dispatch -->|"includes"| node_node_serp
node_node_dispatch -->|"includes"| node_node_zip
node_node_html -->|"uses"| node_node_turndown
node_node_media -->|"routes"| node_node_image
node_node_media -->|"routes"| node_node_audio
node_node_image -->|"uses"| node_node_types
node_node_youtube -->|"fetches"| node_node_files
node_node_zip -.->|"recurses"| node_node_dispatch
node_node_examples -->|"demonstrates"| node_node_dispatch
node_node_tests -->|"verifies"| node_node_dispatch
node_node_ci -->|"builds"| node_node_entry
node_node_ci -->|"checks"| node_node_examples
node_node_ci -->|"runs"| node_node_tests
node_node_ci -.->|"supports"| node_node_types
node_node_dispatch -->|"shares"| node_node_types
node_node_dispatch -.->|"depends on"| node_node_decls

click node_node_entry "https://github.com/dead8309/markitdown-ts/blob/main/src/index.ts"
click node_node_markitdown "https://github.com/dead8309/markitdown-ts/blob/main/src/markitdown.ts"
click node_node_types "https://github.com/dead8309/markitdown-ts/blob/main/src/types.ts"
click node_node_decls "https://github.com/dead8309/markitdown-ts/blob/main/src/declarations.d.ts"
click node_node_turndown "https://github.com/dead8309/markitdown-ts/blob/main/src/custom-turndown.ts"
click node_node_dispatch "https://github.com/dead8309/markitdown-ts/tree/main/src/converters"
click node_node_pdf "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/pdf.ts"
click node_node_docx "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/docx.ts"
click node_node_xlsx "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/xlsx.ts"
click node_node_html "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/html.ts"
click node_node_textxml "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/plain-text.ts"
click node_node_media "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/media.ts"
click node_node_image "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/image.ts"
click node_node_audio "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/wav.ts"
click node_node_youtube "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/youtube.ts"
click node_node_wiki "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/wikipedia.ts"
click node_node_serp "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/bingserp.ts"
click node_node_zip "https://github.com/dead8309/markitdown-ts/blob/main/src/converters/zip.ts"
click node_node_examples "https://github.com/dead8309/markitdown-ts/tree/main/examples"
click node_node_tests "https://github.com/dead8309/markitdown-ts/blob/main/test/index.test.ts"
click node_node_ci "https://github.com/dead8309/markitdown-ts/blob/main/.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_node_entry,node_node_markitdown,node_node_types,node_node_decls,node_node_turndown,node_node_dispatch,node_node_files,node_node_pdf,node_node_docx,node_node_xlsx,node_node_html,node_node_textxml,node_node_media,node_node_image,node_node_audio,node_node_youtube,node_node_wiki,node_node_serp,node_node_zip toneBlue
class node_node_examples toneAmber
class node_node_tests toneMint
class node_node_ci toneRose
```

## Components

### src

Library source and conversion pipeline

- [API entry](https://github.com/dead8309/markitdown-ts/blob/main/src/index.ts): public surface · Library exports for consumers · `src/index.ts`
- [MarkItDown](https://github.com/dead8309/markitdown-ts/blob/main/src/markitdown.ts): orchestrator · Selects converters and normalizes results · `src/markitdown.ts`
- [Types](https://github.com/dead8309/markitdown-ts/blob/main/src/types.ts): shared schema · Shared option and result shapes · `src/types.ts`
- [Decls](https://github.com/dead8309/markitdown-ts/blob/main/src/declarations.d.ts): type shims · Local ambient declarations for dependencies/runtime · `src/declarations.d.ts`
- [Turndown](https://github.com/dead8309/markitdown-ts/blob/main/src/custom-turndown.ts): html rules · Project-specific HTML to Markdown conversion rules · `src/custom-turndown.ts`
- [Converters](https://github.com/dead8309/markitdown-ts/tree/main/src/converters): adapter set · Format-specific conversion modules · `src/converters`
- **Files**: local/remote source · Path, URL, Response, and Buffer ingestion boundary
- [PDF](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/pdf.ts): document converter · PDF extraction to markdown text · `src/converters/pdf.ts`
- [DOCX](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/docx.ts): document converter · Word document conversion · `src/converters/docx.ts`
- [XLSX](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/xlsx.ts): spreadsheet converter · Spreadsheet to markdown tables · `src/converters/xlsx.ts`
- [HTML](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/html.ts): markup converter · HTML to markdown using custom turndown rules · `src/converters/html.ts`
- [Text/XML](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/plain-text.ts): text converters · Plain text and XML/RSS/Atom parsing · `src/converters/plain-text.ts`
- [Media](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/media.ts): media converters · Image and audio conversion pathways · `src/converters/media.ts`
- [Image](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/image.ts): image converter · Image conversion with optional LLM description · `src/converters/image.ts`
- [Audio](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/wav.ts): audio converter · WAV and MP3 handling; transcript not implemented · `src/converters/wav.ts`
- [YouTube](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/youtube.ts): network converter · Transcript extraction from video pages · `src/converters/youtube.ts`
- [Wikipedia](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/wikipedia.ts): network converter · Wikipedia page conversion · `src/converters/wikipedia.ts`
- [Bing SERP](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/bingserp.ts): network converter · Search results page parsing · `src/converters/bingserp.ts`
- [ZIP](https://github.com/dead8309/markitdown-ts/blob/main/src/converters/zip.ts): archive converter · Archive extraction and recursive conversion · `src/converters/zip.ts`

### examples

Executable example packages

- [Examples](https://github.com/dead8309/markitdown-ts/tree/main/examples): example packages · Scenario-focused sample projects · `examples`

### test

Automated conversion fixtures and assertions

- [Tests](https://github.com/dead8309/markitdown-ts/blob/main/test/index.test.ts): fixture suite · Conversion-result verification against representative files · `test/index.test.ts`

### ci

Build, release, and workspace configuration

- [Build/CI](https://github.com/dead8309/markitdown-ts/blob/main/.github/workflows/ci.yml): automation · Workspace, build, and release automation · `.github/workflows/ci.yml`

## Connections

- API entry → MarkItDown: exports · Public API centers on MarkItDown
- MarkItDown → Files: ingests · Accepts paths, URLs, Responses, and Buffers
- MarkItDown → Converters: dispatches · Routes to the matching converter
- MarkItDown → Types: returns · Produces normalized conversion result shapes
- Converters → PDF: includes · Document format adapter
- Converters → DOCX: includes · Document format adapter
- Converters → XLSX: includes · Spreadsheet format adapter
- Converters → HTML: includes · Markup format adapter
- Converters → Text/XML: includes · Text and XML family adapters
- Converters → Media: includes · Media-oriented adapters
- Converters → YouTube: includes · Remote video transcript adapter
- Converters → Wikipedia: includes · Wikipedia page adapter
- Converters → Bing SERP: includes · Search results adapter
- Converters → ZIP: includes · Composite archive adapter
- HTML → Turndown: uses · Applies custom HTML-to-Markdown rules
- Media → Image: routes · Image-specific branch
- Media → Audio: routes · Audio-specific branch
- Image → Types: uses · Shares conversion options and output shapes
- YouTube → Files: fetches · Network-driven source access
- ZIP → Converters: recurses · Nested archive entries re-enter conversion pipeline
- Examples → Converters: demonstrates · Executable reference integrations for each converter family
- Tests → Converters: verifies · Fixture-based conversion coverage
- Build/CI → API entry: builds · Library packaging and validation flow
- Build/CI → Examples: checks · Workspace examples participate in repo automation
- Build/CI → Tests: runs · Automated test suite in CI
- Build/CI → Types: supports · TypeScript and workspace configuration underpin the repo
- Converters → Types: shares · Converters use centralized shared shapes
- Converters → Decls: depends on · Local declarations support implementation/runtime typing