# simonhaenisch/md-to-pdf architecture

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

- Interactive diagram: https://gitdiagram.com/simonhaenisch/md-to-pdf
- Repository: https://github.com/simonhaenisch/md-to-pdf

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript CLI tool (and library) called “md-to-pdf.”
- It ingests Markdown files (or stdin) and outputs PDF files by converting Markdown→HTML→PDF.
- Key libraries: Marked (Markdown→HTML), highlight.js (syntax‐highlighting), Puppeteer (headless‐Chrome→PDF), Chokidar (watch mode).

##### File structure
- Top‐level: package.json, tsconfig*.json, .github/CI, tests, README, etc.
- src/cli.ts: CLI entrypoint (argument parsing, watch‐mode orchestration).
- src/index.ts: programmatic API export.
- src/lib/: core modules—config management, file I/O, HTML generation, HTTP server, PDF rendering.
- src/test/: unit/integration tests and fixtures.

##### README for additional insights
- Describes features (concurrency, watch, custom styles/scripts, front-matter, headers/footers).
- Explains programmatic API.
- Documents dependencies and default behaviors (local file server on random/‐D port, CSS injection, MathJax support).

##### Main components and interactions
- CLI Layer (src/cli.ts)
– Parses CLI arguments (options, paths)
– Decides between one-off conversion or watch mode (uses Chokidar)
- Programmatic API (src/index.ts)
– Exposes mdToPdf({ path|content }, config) → Promise<{ filename, content }>
- Configuration Module (src/lib/config.ts)
– Merges defaults ← config file ← front-matter ← CLI args
- File I/O
– read-file.ts: read Markdown or HTML input
– get-output-file-path.ts: resolve destination path
- Markdown→HTML Conversion
– get-marked-with-highlighter.ts: configure Marked + highlight.js
– get-html.ts: wrap HTML document (styles, scripts, front-matter)
- Static File Server (src/lib/serve-dir.ts)
– Serves baseDir for Puppeteer when loading local assets (images, CSS)
- PDF Rendering (src/lib/md-to-pdf.ts & generate-output.ts)
– Launch Puppeteer (headless Chrome)
– page.setContent(HTML) → page.pdf(options)
- Output
– Write PDF bytes to disk (or return in memory)
- External Services & Libraries
– Marked, highlight.js, Puppeteer, Gray-Matter, Chokidar

1) CLI/API → Config Module
2) Config → File I/O (read Markdown)
3) Markdown + Highlight.js → HTML Generator
4) HTML → (optional) Static HTTP Server → Puppeteer
5) Puppeteer → PDF bytes
6) PDF bytes → File System or stdout

##### Architectural patterns and design principles
- Pipeline pattern: sequential transform steps (read → parse → render → output)
- Modular separation: CLI vs core library vs HTTP server
- Concurrency: Promise.all on multiple files
- Inversion of Control: core mdToPdf function accepts config and input, CLI and API layer simply call into it
- Single responsibility modules (one file = one concern)

##### Detail
- Module filenames or logical names in labels for accuracy.
- Front-matter and config sources as separate inputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Layer"
        direction TB
        CLIParser["CLI Parser<br/>(src/cli.ts)"]:::internal
        API["Programmatic API<br/>(src/index.ts)"]:::internal
    end

    %% Core Library
    subgraph "Core Library Layer"
        direction TB
        Config["Config Merger<br/>(src/lib/config.ts)"]:::internal
        FileReader["File Reader<br/>(src/lib/read-file.ts)"]:::internal
        PathResolver["Output Path Resolver<br/>(src/lib/get-output-file-path.ts)"]:::internal
        MarkdownConv["Markdown→HTML Conversion<br/>(src/lib/get-marked-with-highlighter.ts)"]:::internal
        HTMLGen["HTML Document Generator<br/>(src/lib/get-html.ts)"]:::internal
        StaticServer["Static HTTP Server<br/>(src/lib/serve-dir.ts)"]:::service
        PDFCore["PDF Rendering Core<br/>(src/lib/md-to-pdf.ts)"]:::internal
        PDFOut["PDF Output Generator<br/>(src/lib/generate-output.ts)"]:::internal
        Helpers["Utility Helpers<br/>(src/lib/helpers.ts)"]:::internal
        NodeVal["Node Version Validator<br/>(src/lib/validate-node-version.ts)"]:::internal
        URLCheck["URL Checker<br/>(src/lib/is-http-url.ts)"]:::internal
        MDCheck["Markdown File Checker<br/>(src/lib/is-md-file.ts)"]:::internal
        HelpText["CLI Help Texts<br/>(src/lib/help.ts)"]:::internal
    end

    %% File System
    InputFS["Markdown/Input<br/>(stdin or .md)"]:::filesystem
    OutputFS["PDF Output<br/>(disk or stdout)"]:::filesystem

    %% Third-party libs
    subgraph "External Libraries"
        direction TB
        Marked["Marked"]:::thirdparty
        HighlightJS["highlight.js"]:::thirdparty
        Puppeteer["Puppeteer/Chrome"]:::service
        Chokidar["Chokidar (Watch Mode)"]:::thirdparty
        GrayMatter["Gray-Matter"]:::thirdparty
    end

    %% Watch Mode Loop
    subgraph "Watch Mode (optional)" 
        direction TB
        Chokidar -->|watch events| CLIParser
    end

    %% Data Flow
    CLIParser -->|calls| Config
    API -->|calls| Config
    Config -->|merge sources| FileReader
    Config -->|merge sources| PathResolver
    FileReader -->|raw markdown| MarkdownConv
    HighlightJS --> MarkdownConv
    Marked --> MarkdownConv
    MarkdownConv -->|HTML string| HTMLGen
    HTMLGen -->|complete HTML| StaticServer
    StaticServer -->|serves assets| PDFCore
    Puppeteer --> PDFCore
    PDFCore -->|PDF bytes| PDFOut
    PDFOut -->|write| OutputFS

    %% Utilities
    Config --> Helpers
    Config --> NodeVal
    Config --> URLCheck
    Config --> MDCheck
    CLIParser --> HelpText

    %% Click Events
    click CLIParser "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/cli.ts"
    click API "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/index.ts"
    click Config "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/config.ts"
    click FileReader "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/read-file.ts"
    click PathResolver "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/get-output-file-path.ts"
    click MarkdownConv "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/get-marked-with-highlighter.ts"
    click HTMLGen "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/get-html.ts"
    click StaticServer "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/serve-dir.ts"
    click PDFCore "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/md-to-pdf.ts"
    click PDFOut "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/generate-output.ts"
    click Helpers "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/helpers.ts"
    click NodeVal "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/validate-node-version.ts"
    click URLCheck "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/is-http-url.ts"
    click MDCheck "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/is-md-file.ts"
    click HelpText "https://github.com/simonhaenisch/md-to-pdf/blob/master/src/lib/help.ts"

    %% Styles
    classDef internal fill:#ADF0FF,stroke:#03689A,color:#000;
    classDef filesystem fill:#C2F784,stroke:#2F7F00,color:#000,stroke-dasharray: 5 5;
    classDef service fill:#D3C0F8,stroke:#520DA7,color:#000;
    classDef thirdparty fill:#F8C17D,stroke:#A65B00,color:#000;
```
