# l1xnan/obsidian-better-export-pdf architecture

> Architecture diagram of the GitHub repository l1xnan/obsidian-better-export-pdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/l1xnan/obsidian-better-export-pdf
- Repository: https://github.com/l1xnan/obsidian-better-export-pdf

## Overview

##### Project Type and Purpose
- This is an Obsidian community plugin (“Better Export PDF”) written in TypeScript and Svelte.
- It hooks into the Electron‐based Obsidian host to provide enhanced PDF export capabilities (outline bookmarks, preview, metadata, batch export, etc.).

##### Architectural Overview
Break the system into four main layers:
A. Obsidian Host (Electron)
B. Plugin Core
C. UI Layer (Svelte Components)
D. PDF Rendering & Filesystem

##### Main Components
1. Obsidian API Layer
- The host application that loads the plugin via `manifest.json`.
- Provides plugin lifecycle methods (`onload`, `onunload`), command registration, and webview tag for PDF.
2. Plugin Core (src/*.ts)
- main.ts – Entry point. Registers commands, menu items, context actions.
- modal.ts – Controls the export dialog lifecycle and collects user settings.
- render.ts / pdf.ts – Renders Markdown to HTML, injects CSS, calls `webview.printToPDF(options)`.
- setting.ts – Reads and persists plugin configuration.
- utils.ts, constant.ts, type.d.ts – Shared helpers, constants, and TypeScript types.
- version-bump.mjs / versions.json – Release management.
3. UI Layer (Svelte)
- Progress.svelte – Shows export progress bar.
- i18n folder – Localization strings for English and Chinese.
4. Assets & Styling
- assets/ – Preview screenshots used in README.
- styles.css – Global CSS overrides for print styling.
- manifest.json – Plugin metadata (name, version, author, commands).
- esbuild.config.mjs – Build setup for bundling TS and Svelte into a single plugin JS file.

##### Data Flows and Interactions
- User triggers export (via context menu or command).
↓
- main.ts invokes modal.ts to open Svelte-based export dialog.
↓
- User selects options (page size, margins, CSS snippets, metadata). Svelte UI writes settings to setting.ts.
↓
- Plugin core reads Markdown content from Obsidian vault.
↓
- render.ts converts Markdown to HTML, applies CSS (styles.css + user snippets).
↓
- pdf.ts spins up a hidden `<webview>` instance, loads HTML, calls `webview.printToPDF(options)`.
↓
- The resulting PDF bytes are written to disk via the Obsidian filesystem API.
↓
- Progress.svelte displays real-time progress; concurrency limit enforced in pdf.ts.
↓
- On completion, plugin notifies Obsidian and optionally opens the PDF.

##### Architectural Patterns & Design Principles
- Modular separation: UI (Svelte) vs. core logic (TypeScript).
- Single responsibility: each .ts file handles one concern (settings, rendering, PDF calls).
- Concurrency control during batch export to limit resource usage.
- Plugin manifest declares the extension points (commands, settings).
- Localization via i18n folder.

- Plugin files vs. Obsidian/Electron APIs vs. external resources

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Obsidian Host Layer
    subgraph "Obsidian Host (Electron)"
        direction TB
        Manifest["manifest.json\n(Plugin Manifest)"]:::config
        API["Obsidian API\n(plugin lifecycle, webview, fs)"]:::external
    end

    %% Plugin Core Layer
    subgraph "Plugin Core (TypeScript)" 
        direction TB
        Main["src/main.ts\n(Entry & Command Registration)"]:::core
        Modal["src/modal.ts\n(Export Dialog Controller)"]:::core
        Render["src/render.ts\n(Markdown→HTML Renderer)"]:::core
        PDF["src/pdf.ts\n(PDF Engine & Webview)"]:::core
        Setting["src/setting.ts\n(Settings Persistence)"]:::core
        Const["src/constant.ts\n(Shared Constants)"]:::core
        Util["src/utils.ts\n(Utility Functions)"]:::core
        Types["src/type.d.ts\n(Type Definitions)"]:::core
    end

    %% UI Layer
    subgraph "UI Layer (Svelte)" 
        direction TB
        Progress["src/Progress.svelte\n(Progress Bar)"]:::ui
        I18nIndex["src/i18n/index.ts\n(Locale Loader)"]:::ui
        I18nEN["src/i18n/en.ts\n(English Strings)"]:::ui
        I18nZH["src/i18n/zh.ts\n(Chinese Strings)"]:::ui
    end

    %% Assets & Styling
    subgraph "Assets & Styling & Build & Release" 
        direction TB
        Assets["assets/\n(Preview Screenshots)"]:::config
        Styles["styles.css\n(Print CSS Overrides)"]:::config
        Build["esbuild.config.mjs\n(Build Config)"]:::config
        Bump["version-bump.mjs\n(Release Script)"]:::config
        Versions["versions.json\n(Version History)"]:::config
    end

    %% Connections
    Manifest -->|"loads plugin"| Main
    Main -->|"open export dialog"| Modal
    Modal -->|"render dialog"| Progress
    Modal -->|"load locale"| I18nIndex
    I18nIndex --> I18nEN
    I18nIndex --> I18nZH
    Modal -->|"read/write settings"| Setting
    Modal -->|"invoke renderer"| Render
    Render -->|"get CSS snippets"| Setting
    Render -->|"apply global CSS"| Styles
    Render -->|"produce HTML"| PDF
    PDF -->|"webview.printToPDF()"| API
    PDF -->|"get concurrency limit"| Setting
    PDF -->|"write PDF to disk"| API
    PDF -->|"update progress"| Progress
    PDF -->|"notify completion"| API

    %% Click Events
    click Manifest "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/manifest.json"
    click Build "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/esbuild.config.mjs"
    click Main "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/main.ts"
    click Modal "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/modal.ts"
    click Render "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/render.ts"
    click PDF "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/pdf.ts"
    click Setting "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/setting.ts"
    click Const "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/constant.ts"
    click Util "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/utils.ts"
    click Types "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/type.d.ts"
    click Progress "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/Progress.svelte"
    click I18nIndex "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/i18n/index.ts"
    click I18nEN "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/i18n/en.ts"
    click I18nZH "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/src/i18n/zh.ts"
    click Assets "https://github.com/l1xnan/obsidian-better-export-pdf/tree/master/assets/"
    click Styles "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/styles.css"
    click Bump "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/version-bump.mjs"
    click Versions "https://github.com/l1xnan/obsidian-better-export-pdf/blob/master/versions.json"

    %% Styles
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef core fill:#9fdf9f,stroke:#333,stroke-width:1px
    classDef ui fill:#9fdfff,stroke:#333,stroke-width:1px
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
```
