typora-plugin-lite (tpl)

typora-plugin-lite (abbreviated as tpl) is a lightweight, cross-platform, and minimal-invasiveness plugin system for Typora.

It is designed to solve the cross-platform compatibility issues of existing plugin systems, particularly on macOS where Typora is a native Swift/WKWebView application rather than Electron.

Warning

Under active development. Use at your own risk. The architecture and APIs are subject to change without notice.

---

🚀 Key Features

• Cross-Platform First: Unified abstraction layer for macOS (WKWebView) and Windows/Linux (Electron).
• Micro-kernel Architecture: A minimal loader.js (approx. 30 lines) triggers a dynamic ESM core.js.
• Lazy Loading: Plugins are only loaded when triggered by startup, events, commands, or hotkeys (inspired by lazy.nvim).
• Standard-Compatible Metadata: Uses YAML frontmatter and HTML comments (tpl markers) to store plugin data, ensuring zero conflict with other Markdown renderers.
• Spotlight UI: A decoupled, high-performance UI runtime for search, commands, and navigation.
• External Storage: Plugin settings, logs, and caches live outside Typora's bundled resources. On Linux, both third-party plugins and persistent data are stored exclusively under ~/.local/Typora/ (plugins/ for bundles, data/ for state).
• Session Archive CLI: Export a Codex or Claude Code session into a private, Typora-friendly Markdown note without loading a Typora plugin.

---

🏗️ Architecture

graph TD
    App[Typora App] --> Loader[loader.js - Injected Entry]
    Loader --> Core[core.js - Micro-kernel]
    Core --> Plat[Platform Abstraction - fs/shell/path]
    Core --> PM[Plugin Manager - Lazy Load]
    Core --> UI[UI Runtime - Spotlight/Toast]
    Core --> Editor[Editor API - Markdown/Fences]
    PM --> Plugins[Independent ESM Plugins]

Loading

Platform Abstraction

Plugins never touch low-level APIs directly. They use platform.fs, platform.shell, and platform.path, which automatically switch between:

• macOS: bridge.callHandler and shell command execution.
• Win/Linux: Node.js fs, path, and child_process modules.

---

📦 Included Plugins

Plugin	Complexity	Strategy	Description
md-padding	S	startup	Automatically format Chinese/English spacing.
fence-enhance	S	startup	Add copy button to code fences.
code-viewer	M	startup	Open non-Markdown text and code files in a read-only, syntax-highlighted view.
sidenote	M	startup	Render inline <span class="sidenote"> as margin notes inside the editor.
wider	M	startup	Switch editor width between default / wide / full with sidenote-aware spacing.
title-shift	S	hotkey	Quickly shift heading levels.
fuzzy-search	M	hotkey	Quick-open with fzf-style ranking, relative-path matching, and rg/fallback indexing.
note-assistant	M	hotkey	Show graph-based related notes and insert wiki-links from the current document.
remote-control	L	startup	Loopback JSON-RPC surface for external agents / CLIs. See plugin README.

wider at a glance

• Feishu-like default / wide / full writing widths
• Mod+[ narrows, Mod+] widens
• Shortcut-only switching with a brief mode toast
• Auto-reserves the sidenote gutter when sidenote is active

sidenote table behavior

• Desktop sidenotes are rendered into a dedicated right-side portal layer in the editor
• Table horizontal scrolling remains intact
• Sidenotes stay docked on the outer editor gutter instead of participating in block layout

Archive Codex / Claude Code conversations

The standalone session-archive tool recovers visible user/agent turns, tool calls and results from local provider JSONL files. It excludes hidden reasoning and instructions, redacts common credentials and home paths, neutralizes active HTML, and publishes the note atomically with private file permissions.

npm run build
node dist/tools/session-archive/index.mjs codex <session-id> -o session.md
node dist/tools/session-archive/index.mjs claude <session-id> -o session.md
node dist/tools/session-archive/index.mjs codex <session-id> --output-dir ~/Notes/Agents --max-file-size 4MiB
node dist/tools/session-archive/index.mjs codex <session-id> --output-dir ~/Notes/Agents --mode answers

Directory output automatically switches from one note to an indexed set of size-limited parts for long sessions. Start with the complete Session Archive tutorial, or see the concise tool reference for heading structure, title discovery, export modes, failure semantics, privacy boundaries, and the companion Claude-like Session themes.

---

🛠️ Installation

Prerequisites

• Typora installed
• Node.js (v22+) and pnpm for building from source

Step 1: Clone & Build

git clone https://github.com/lr00rl/typora-plugin-lite.git
cd typora-plugin-lite
pnpm install
pnpm build

Step 2: Run Installer

The installer automatically detects your Typora installation, backs up window.html, injects the loader script, and copies plugin files into Typora's resources directory.

macOS

./packages/installer/install.sh

The script searches these default locations:

• /Applications/Typora.app

If Typora is installed elsewhere:

./packages/installer/install.sh -p /path/to/Typora.app

Note: On macOS, the installer will re-sign the app bundle to maintain code signature validity. You may be prompted for your password.

Linux

sudo ./packages/installer/install.sh

sudo is required because Typora's resources directory (e.g. /usr/share/typora/resources/) is typically owned by root.

The script searches these default locations:

• /usr/share/typora
• /usr/local/share/typora
• /opt/typora
• ~/.local/share/Typora

If Typora is installed elsewhere:

sudo ./packages/installer/install.sh -p /path/to/typora

Windows

Open PowerShell as Administrator, then run:

powershell -ExecutionPolicy Bypass -File packages\installer\bin\install-windows.ps1

The script searches these default locations:

• C:\Program Files\Typora
• C:\Program Files (x86)\Typora
• %LOCALAPPDATA%\Programs\Typora
• Windows Registry install records

If Typora is installed elsewhere:

powershell -ExecutionPolicy Bypass -File packages\installer\bin\install-windows.ps1 -Path "D:\Apps\Typora"

Note: Administrator privileges are needed to write to Typora's installation directory.

Step 3: Restart Typora

Close and reopen Typora. Open DevTools (Shift+F12 on Linux/Windows, or Option+Command+I on macOS) and check the console for:

[tpl:loader] done

On Linux, third-party plugin bundles and all persistent plugin data are stored exclusively under ~/.local/Typora/:

~/.local/Typora/plugins      # Third-party plugin bundles (manifest.json + main.js)
~/.local/Typora/data         # Settings, caches, logs (created on demand)

Legacy ~/plugins/ paths are no longer read or migrated. If you have data under ~/plugins/data/, move it into ~/.local/Typora/data/ (or let plugins regenerate their state on next launch) and delete the old directory.

Uninstall

Restore the original window.html from backup:

# The backup is at: <typora-resources>/window.html.tpl-backup
# Linux example:
sudo cp /usr/share/typora/resources/window.html.tpl-backup /usr/share/typora/resources/window.html

Or simply reinstall/update Typora — the plugin injection will be replaced by the fresh window.html.

---

🤝 Contributing

We welcome contributions of all kinds! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your help is appreciated.

1. Report Issues: Found a bug? Open an issue.
2. Submit PRs: Feel free to fork and submit pull requests. Please follow the existing code style.
3. Plugin Development: Check the docs/plugin-dev-guide.md (coming soon) to start building your own plugins.

---

📜 License

MIT License. See LICENSE for details.