docs: add Theming Publisher guide#320
Open
mlennie wants to merge 4 commits into
Open
Conversation
Documents the four configuration surfaces for Publisher chart, table, and dashboard tile colors: instance and environment theme blocks in publisher.config.json, the in-app Theme Editor at /settings/theme, and per-chart `# theme.*` annotations. Covers the cascade order, the full palette key set (per-mode background, tableHeader, tableHeaderBackground, tableBody, tile, tileTitle, mapColor; shared series + font), light/dark mode behavior, and current theme-control limits. Adds a cross-link from publishing.malloynb so the main publishing guide points readers at the new doc. Signed-off-by: Monty Lennie <[email protected]>
The initial draft predated the theming PR review and described behavior that does not match what shipped. Corrected and fact-checked against the merged Publisher/renderer code: - The in-app Theme Editor edits the single instance theme (not a per-environment theme), and its UI is four cards (Charts, Maps, Tables, Typography) with a per-card inline preview, not six sections plus one preview pane. - The runtime theme store is DuckDB, not SQLite. - publisher.config.json's `theme` only seeds the store on first boot; later JSON edits need `--init` or the editor's "Reset to defaults" to re-apply. Added an "applying config changes" note and dropped the implication that a plain restart re-reads the config. - Per-environment themes (environments[].theme) are reserved in the schema but not yet applied by any viewer; documented the three working surfaces and moved per-environment to "what is not theme-controlled yet". - `palette.mapColor` applies to choropleth maps only; rect-mark heatmaps keep their built-in scheme. - The logo note pointed at a non-existent `MalloyPublisherApp` component; corrected to the real app-shell `logoHeader` prop. - Theme changes apply immediately in the editing tab and to other viewers on their next page load (not "the next render in any tab"). - Added a security note: open-source Publisher does not authenticate requests, so the editor and PUT/DELETE /api/v0/theme are reachable by anyone who can reach the server; run behind an auth layer / trusted network and use frozenConfig where the theme must not be mutable. Softened the frozenConfig line since the theme is served from the store, not necessarily the config file. This matches the Publisher README and api-doc. Signed-off-by: Monty Lennie <[email protected]>
The guide shipped without a table-of-contents entry, so it was only reachable by direct URL. Adds it to the Publishing group after "MCP for AI Agents". The closing reference pointed at README.md#theming. Publisher moved that content to docs/theming.md and the README now only links to it from a table, so the anchor no longer resolves. Points at docs/theming.md instead. Signed-off-by: Monty Lennie <[email protected]>
mlennie
force-pushed
the
docs/theming-guide
branch
from
July 20, 2026 19:27
dbac07b to
cf4af05
Compare
The site now documents two different `theme.*` grammars. The model-options page teaches flat keys inherited from the bare renderer; the new Publisher guide teaches the namespaced ones Publisher actually reads. Nothing pointed from either to the other, so a reader following the wrong one gets no error, just no effect. Publisher supplies most of those flat properties itself, and a caller-supplied theme is resolved ahead of both `# theme.*` and `## theme.*`, so only the four weight and spacing keys fall through. Says so, and points at the guide. Also drops a colour claim about heatmap gradients that only held for some mark types, and replaces the "use a per-chart annotation instead" line: a model-level `## theme.*` themes a whole file, which is the real answer for that case. Signed-off-by: Monty Lennie <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Walkthrough video: https://www.loom.com/share/e31e852ca1664526a1e7a355a07bddd6 (recorded before the correction commit below, so parts of it show the earlier draft's behavior)
Adds a Theming Publisher user guide. It documents the three ways to set Publisher's chart, table, and dashboard-tile colors: the instance
themeblock inpublisher.config.json, the in-app Theme Editor at/settings/theme, and per-chart# theme.*annotations. Covers the cascade (a per-chart annotation over the instance theme over Publisher's built-in defaults), the full palette key set (per-mode background, tableHeader, tableHeaderBackground, tableBody, tile, tileTitle, mapColor; shared series + font), light/dark mode behavior, how a configthemeedit is re-applied (it seeds the runtime store on first boot, so use--initor the editor's "Reset to defaults" afterward), and current theme-control limits (per-environment themes are reserved in the schema but not yet applied by any viewer).The guide was fact-checked against the shipped Publisher and renderer code. The second commit (
dbac07b) corrects the initial draft to match it: the editor is instance-wide (not per-environment), the runtime store is DuckDB (not SQLite),mapColorapplies to choropleth maps only (not heatmaps), the editor UI is four cards (Charts/Maps/Tables/Typography) with per-card previews, and it adds a security note that open-source Publisher does not authenticate requests (so the editor andPUT /api/v0/themeare reachable by anyone who can reach the server; run behind an auth layer or trusted network, and usefrozenConfigwhere the theme must not be mutable).Adds a cross-link from
publishing.malloynbso the main publishing guide points readers at the new doc.