How benjypng/logseq-toc-plugin works
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