# benjypng/logseq-toc-plugin architecture

> Architecture diagram of the GitHub repository benjypng/logseq-toc-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benjypng/logseq-toc-plugin
- Repository: https://github.com/benjypng/logseq-toc-plugin

## Overview

##### Project Type and Purpose
- This is a single‐page, front‐end plugin that integrates into a host markdown environment (e.g., a note-taking or documentation app).
- It parses markdown headers in real time and renders a style-able Table of Contents (TOC), both as a page-level sidebar and as an inline block.

##### File Structure
- Top-Level Files
- index.html – the plugin’s HTML entry point
- package.json, pnpm-lock.yaml – Node.js package metadata and lock file
- vite.config.ts, tsconfig.json, eslint.config.mjs, .prettierrc – build, TypeScript, and lint/prettier config
- src Directory
- src/index.tsx – bootstrap and mount the React plugin in the host environment
- src/features/PageToc.tsx (+ page-toc.css) – core React component that renders TOC
- src/libs/get-headers-arr.ts – logic to parse markdown headers into a structured array
- src/settings.ts – plugin configuration schema and defaults
- src/page-toc-css.d.ts – type definitions for CSS modules
- .github/workflows/publish.yml – CI pipeline for publishing the plugin to its marketplace

##### README for Additional Insights
- Runtime behavior
- On page load, automatically render a sidebar TOC if markdown headers exist
- Expose a slash‐command to insert an inline TOC block
- Styling
- CSS classes documented for custom themes via a host custom.css override

##### Main Components
A. Build & Toolchain
- Node.js + pnpm
- Vite (dev server, build pipeline)
- TypeScript transpilation
- ESLint/Prettier (code quality)
B. Plugin Runtime
1. Host Environment (e.g., the note app)
– Loads index.html
– Provides markdown document and plugin APIs
2. Plugin Entry (index.tsx)
– Initializes the React root
– Registers event handlers (page load, slash commands)
3. Core Logic
– get-headers-arr (parses markdown headers)
– PageToc component (receives header array + settings, renders TOC)
– CSS modules for styling
4. Settings Module
C. External/Marketplace
- CI/CD workflow publishes to plugin marketplace
- Sponsor links and installation via marketplace

##### Relationships & Data Flow
- Build Pipeline → generates a bundled plugin (JS/CSS)
- Host Environment loads the bundle
- On page render:
- Host provides raw markdown content → get-headers-arr
- Parsed header list → PageToc
- PageToc + CSS → DOM updates sidebar or inline block
- User triggers `/Insert inline Table of Contents` command → Plugin re-executes parsing and rendering for target block

##### Architectural Patterns & Principles
- Component-based UI (React)
- Separation of concerns:
- Parsing logic separated in libs/
- Rendering logic in features/
- Configuration in settings/
- Build vs. runtime clearly demarcated via Vite config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI" 
        direction TB
        B1["package.json"]:::build
        B2["pnpm-lock.yaml"]:::build
        B3["vite.config.ts"]:::build
        B4["tsconfig.json"]:::build
        B5["eslint.config.mjs"]:::build
        B6[".prettierrc"]:::build
        B7[".github/workflows/publish.yml"]:::build
        BuildProcess["Vite Build / Dev Server"]:::build
        Bundle["Bundled JS/CSS"]:::build
    end

    %% Runtime Environment Layer
    subgraph "Runtime Environment"
        direction TB
        H1["Host Environment"]:::runtime
        H2["index.html"]:::runtime
    end

    %% Plugin Entry & Integration
    subgraph "Plugin Entry & Integration"
        direction TB
        P1["src/index.tsx"]:::runtime
    end

    %% Plugin Internal Modules
    subgraph "Plugin Modules"
        direction TB
        M1["src/libs/get-headers-arr.ts"]:::internal
        M2["src/features/PageToc.tsx"]:::internal
        M3["src/features/page-toc.css"]:::internal
        M4["src/page-toc-css.d.ts"]:::internal
        M5["src/settings.ts"]:::internal
    end

    %% External Marketplace
    Marketplace["Plugin Marketplace"]:::external

    %% Connections: Build
    B1 & B2 & B3 & B4 & B5 & B6 --> BuildProcess
    BuildProcess --> Bundle
    BuildProcess -->|uses eslint/prettier| B5
    BuildProcess -->|uses eslint/prettier| B6

    %% Runtime Load
    Bundle --> H2
    H2 --> P1
    P1 --> H1

    %% Runtime Flow
    H1 -->|provides raw markdown| M1
    P1 -->|initializes & registers| M1
    M1 -->|header array| M2
    M2 -->|renders TOC| H1
    M2 -->|applies styles| M3
    M2 -->|type definitions| M4
    M2 -->|reads config| M5
    H1 -->|slash command| P1

    %% CI Publish
    B7 -->|publishes bundle| Marketplace

    %% Click events
    click B1 "https://github.com/benjypng/logseq-toc-plugin/blob/main/package.json"
    click B2 "https://github.com/benjypng/logseq-toc-plugin/blob/main/pnpm-lock.yaml"
    click B3 "https://github.com/benjypng/logseq-toc-plugin/blob/main/vite.config.ts"
    click B4 "https://github.com/benjypng/logseq-toc-plugin/blob/main/tsconfig.json"
    click B5 "https://github.com/benjypng/logseq-toc-plugin/blob/main/eslint.config.mjs"
    click B6 "https://github.com/benjypng/logseq-toc-plugin/blob/main/.prettierrc"
    click B7 "https://github.com/benjypng/logseq-toc-plugin/blob/main/.github/workflows/publish.yml"
    click H2 "https://github.com/benjypng/logseq-toc-plugin/blob/main/index.html"
    click P1 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/index.tsx"
    click M1 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/libs/get-headers-arr.ts"
    click M2 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/features/PageToc.tsx"
    click M3 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/features/page-toc.css"
    click M4 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/page-toc-css.d.ts"
    click M5 "https://github.com/benjypng/logseq-toc-plugin/blob/main/src/settings.ts"

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085,color:#004085;
    classDef runtime fill:#d4edda,stroke:#155724,color:#155724;
    classDef internal fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
