Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Document the Themes plugin (PRD-7881) (#3398)
serafin-garciafe26ef2d8a35
diff --git a/docs/content/plugins/meta.json b/docs/content/plugins/meta.jsonindex 4b87a4fef..0a05356ab 100644--- a/docs/content/plugins/meta.json+++ b/docs/content/plugins/meta.json@@ -1,5 +1,5 @@{"title": "Plugins","icon": "LuBlocks",- "pages": ["overview", "slidev"]+ "pages": ["overview", "slidev", "themes"]}diff --git a/docs/content/plugins/overview.mdx b/docs/content/plugins/overview.mdxindex ad50cbc52..107bbd4aa 100644--- a/docs/content/plugins/overview.mdx+++ b/docs/content/plugins/overview.mdx@@ -1,10 +1,10 @@---title: Overviewicon: LuBookOpen-description: Optional capabilities that ship with OpenKnowledge but stay off until you turn them on — linters, themes, and the Slidev presentation renderer.+description: Optional capabilities that ship with OpenKnowledge, most of them off until you turn them on. Linters, themes, and the Slidev presentation renderer.----A plugin is an optional capability that ships with OpenKnowledge and stays off until you turn it on. Each one belongs to a scope, and the scope decides who else gets it:+A plugin is an optional capability that ships with OpenKnowledge. Most stay off until you turn them on (Themes is the exception: it ships enabled). Each one belongs to a scope, and the scope decides who else gets it:- **Project plugins** are saved to the project's `config.yml`. Commit it and every collaborator gets the same setting.- **User plugins** are personal to your device. They live in your user config and are never committed.@@ -27,6 +27,6 @@ Flip the switch. Open editors react live; there is no restart and no Save button| [markdownlint](/docs/advanced/content-rules/markdownlint) | Project | Flags markdown style problems as you write — hard tabs, heading increments, list markers, and the rest of the standard rule set. || [Frontmatter schemas](/docs/advanced/content-rules/frontmatter) | Project | Validates document frontmatter against standard JSON Schema files. Beta. || [Slidev](/docs/plugins/slidev) | User | Presents a document as a slide deck in its own window. Desktop only; needs the Slidev CLI installed separately. Beta. |-| Themes | User | A personal color-theme picker. See the [configuration reference](/docs/reference/configuration) for the keys it writes. |+| [Themes](/docs/plugins/themes) | User | A personal color-theme picker: one palette per light mode and one per dark, built-in or your own base16 schemes. |markdownlint and Frontmatter schemas are both **content rules**, a shared non-blocking linting layer. What they have in common — where problems appear, the Problems panel, `ok lint`, agent advisories — is on the [content rules overview](/docs/advanced/content-rules/overview).diff --git a/docs/content/plugins/themes.mdx b/docs/content/plugins/themes.mdxnew file mode 100644index 000000000..6c6723aa0--- /dev/null+++ b/docs/content/plugins/themes.mdx@@ -0,0 +1,36 @@+---+title: Themes+icon: LuPalette+description: Recolor the editor with built-in palettes or your own base16 schemes, one palette per light mode and one per dark, saved as portable YAML files.+---++Themes recolors the whole OpenKnowledge interface with a [base16](https://github.com/tinted-theming/schemes) palette. It's a user plugin: on by default, personal to your device, never committed.++Open **Settings → Plugins → Themes**. The page is a gallery of tiles: **Default**, the built-ins (Dracula, Catppuccin Frappé, Catppuccin Latte, Monokai, Gruvbox, Solarized), and any themes you've created, plus a **Create new theme** tile.++## One palette per mode++Every tile carries a sun and a moon: the sun assigns that palette to light mode, the moon to dark mode. Clicking the tile itself assigns it to whichever mode is currently active. The light/dark switch in **Settings → Preferences** decides which of the two slots is live. On **System**, your OS does, so the palette follows the OS appearance.++A palette forces its own light or dark variant wherever it sits. Put Dracula in the light slot and switching to light mode shows Dracula's dark colors: the slot decides *when* a palette applies, and the palette decides how it looks. **Default** means no palette: the base stylesheet shows through.++Selections are saved to your user config as `appearance.colorThemeLight` / `appearance.colorThemeDark`. See the [configuration reference](/docs/reference/configuration).++## Create your own++Click **Create new theme**, name it, and the editor opens. Two ways to fill it in:++- **Paste a scheme.** The paste box accepts any [Tinted Theming](https://github.com/tinted-theming/schemes) base16 scheme (hundreds are published), in either the current layout (`palette:` nested) or the original chriskempson one, YAML or JSON.+- **Edit the sixteen slots by hand.** Each `base00`–`base0F` slot names its role. Edits apply live and save automatically.++**Copy as YAML** exports the scheme in the standard layout, so a theme you tuned here is pasteable anywhere else in the base16 ecosystem.++## Theme files++Saved themes are plain Tinted Theming YAML files in `~/.ok/themes/`, one file per theme, filename as identity. Drop a downloaded scheme file there (`.yaml` or `.yml` only) and it appears in the gallery, since the folder is re-scanned when the Themes page opens. A file that doesn't parse is listed with the reason rather than silently dropped, so it can always be fixed.++Deleting a theme from its tile deletes the file, with an undo window before it's gone for good.++## Turn it off++Themes ships enabled. Switch it off in **Settings → User ▸ Plugins**: the palette drops back to the default stylesheet and the page leaves the sidebar. Your selections stay in config, so switching it back on restores them.diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex b48b3f221..40389abac 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -38,7 +38,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi| `contentRules.frontmatter.schemas` | array | `[]` | project | Frontmatter schema mappings: each entry scopes one JSON Schema file to a set of docs — `file` (project-root-relative path), optional `appliesTo` (glob or list; leading `!` excludes; absent means every doc), optional `enabled: false` to park a mapping. Schema content lives in the mapped files, not here. See [Frontmatter schemas](/docs/advanced/content-rules/frontmatter). || `appearance.theme` | `"light" \| "dark" \| "system"` | (unset) | user | Editor light/dark theme. || `appearance.language` | `"system" \| "en" \| "zh-Hans" \| "zh-Hant" \| "hi" \| "es" \| "ar" \| "fr" \| "bn" \| "pt-BR" \| "id" \| "ur"` | (unset) | user | Interface language. `system` (the effective value when unset) follows your operating system or browser, and keeps following it. A personal preference, not project-shared — and it applies to the app's own chrome only: your documents, titles, file and folder names, frontmatter values and tags stay in the language you wrote them in. **Settings → Preferences → Language** offers nine of them (English, 简体中文, 繁體中文, हिन्दी, Español, Français, বাংলা, Português do Brasil, Indonesia). Every catalog is complete, but only `es` has been through a Spanish reader; the rest, `zh-Hans` included, are machine-translated and nobody who reads them has checked the wording. Treat it as provisional and [tell us what is wrong](/docs/contribute/translations). `ar` and `ur` are complete translations too, but they stay out of the picker until the interface lays out right to left; set either here by hand to run the app in it, and note the app will not select them from your OS language alone. `OK_LANG=<tag>` overrides the desktop app's native menus for a single run; the rest of the interface follows this field. |-| `appearance.colorThemeLight` | theme id (`[a-z0-9-]`, 1–32 characters) | (unset) | user | IDE color palette applied while the resolved mode is light. Built-in ids include `default`, `dracula`, `catppuccin-frappe`, `catppuccin-latte`, `monokai`, `gruvbox`, `solarized`, and `custom`; saved themes use their generated `saved-*` id. `default` (the effective value when unset or when no available palette matches an explicitly configured id) means no palette — the base stylesheet shows through. `custom` applies `appearance.customTheme`. Pick it in **Settings → Plugins → Themes** with the tile's sun. |+| `appearance.colorThemeLight` | theme id (`[a-z0-9-]`, 1–32 characters) | (unset) | user | IDE color palette applied while the resolved mode is light. Built-in ids include `default`, `dracula`, `catppuccin-frappe`, `catppuccin-latte`, `monokai`, `gruvbox`, `solarized`, and `custom`; saved themes use their generated `saved-*` id. `default` (the effective value when unset or when no available palette matches an explicitly configured id) means no palette — the base stylesheet shows through. `custom` applies `appearance.customTheme`. Pick it in **Settings → Plugins → [Themes](/docs/plugins/themes)** with the tile's sun. || `appearance.colorThemeDark` | theme id (`[a-z0-9-]`, 1–32 characters) | (unset) | user | IDE color palette applied while the resolved mode is dark — the tile's moon. Built-in and saved-theme ids follow the same constrained string grammar. `appearance.theme` chooses between the two; on `system` your OS does, so the palette follows the OS appearance. Any available palette may sit in either slot, and it keeps forcing its own light/dark variant. An explicitly configured id that is not available falls back to `default`. || `appearance.colorTheme` | theme id (`[a-z0-9-]`, 1–32 characters) | (unset) | user | Legacy single-palette field, superseded by `colorThemeLight` / `colorThemeDark` above. A valid available id supplies the palette only for a slot that is truly unset; an explicit unknown per-mode id falls back to `default` instead of reviving this legacy value. Writing either slot from **Settings → Plugins → Themes** removes this key. || `appearance.colorThemeEnabled` | boolean | `true` | user | Whether the Themes plugin appears in **Settings → Plugins**. On by default (absent = enabled). |diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 84d9cf44c..198887bc4 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -130,6 +130,7 @@ On each launch and project open, the app also runs **repair sweeps**: it rewrite| `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No || `~/.agents/skills/<name>/`, `~/.claude/skills/<name>/`, … | Your global-scope skills, versioned in place in your home editor dirs (kept by `ok uninstall` unless `--purge-content`) | No || `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |+| `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No || `~/.ok/mcp-status.json` | First-launch MCP consent record | No || `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`) | No || `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](#shell-and-path) above) | No |@@ -254,6 +255,7 @@ Disable all three with `OK_RECLAIM_DISABLE=1`.| `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No || `~/.agents/skills/<name>/`, `~/.claude/skills/<name>/`, … | Your global-scope skills, versioned in place in your home editor dirs (kept by `ok uninstall` unless `--purge-content`) | No || `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |+| `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No || `~/.ok/logs/` | CLI logs (`cli.<date>.log`), size- and age-capped | No || `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`) | No |