# Obsidian Publish Customize > Customize an Obsidian Publish site through the publish.css and publish.js root hooks — theming with Publish CSS variables, and scripting the rendered page (injecting frontmatter blocks, nav, widgets). Use when editing publish.css/publish.js files, theming a Publish site, or working around Publish's undocumented client-side behavior. NOT for Publish usage, Obsidian desktop-app theming, or plugin development. - Skill: `nweii/obsidian-publish-customize` (Agent Skill) - Install (CLI): `npx skillmds add nweii/obsidian-publish-customize` - Raw SKILL.md: https://api.skillmd.com/api/skills/nweii/obsidian-publish-customize/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: nweii (https://skillmd.com/u/nweii) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/nweii/obsidian-publish-customize --- # Obsidian Publish customization Obsidian Publish hosts a vault as a website. Two root files are the only hooks for changing it beyond the built-in site options: `publish.css` (custom styles) and `publish.js` (custom scripts). Both are supported insertion points, but almost everything past basic theming is undocumented — you script against Publish's rendered DOM and private globals, which can change without notice. - Both files live at the **vault root** (`/publish.css`, `/publish.js`). Hidden from the file explorer by default; publish them from the **Publish changes** dialog. - `publish.js` **only runs on a custom domain.** On the default `publish.obsidian.md/` URL it's inert. `publish.css` works everywhere. **Scope.** Theming via Publish CSS variables, and scripting the rendered page via publish.js. Out of scope, kept separate as three documentation domains: - Normal Publish operation — publishing notes, custom-domain setup, the Publish CLIs. - Obsidian *desktop-app* theming — themes and CSS snippets inside the app. - Plugin development — the developer API for community plugins. CSS variables overlap between app and Publish (see Theming), but the app's theming workflow and the plugin API are separate references — don't conflate them. ## Pushing and iterating Publishing the root files needs an active Publish subscription and one of two CLIs, depending on the environment: - **Desktop app available:** the Obsidian app CLI publishes a file directly — `obsidian publish:add path=publish.css` (or `path=publish.js`); needs the desktop app running. Its `publish:list`/`status`/`site` commands may return no output, so there's no reliable confirmation a push landed — verify in the browser. - **Headless / CI (no desktop app):** the `obsidian-headless` CLI (`ob` via `bun` or `npm install -g obsidian-headless`) publishes from the command line. After `ob login` and `ob publish-setup --site `, run `ob publish` — by default it includes only `publish: true` notes, so add `--all` to include the root static assets, and `--dry-run` to preview. `ob publish-site-options` sets the site toggles non-interactively. Then, regardless of which CLI pushed: - Publish CDN-caches assets; **hard-refresh** after every push. - **Test publish.js in the browser console before committing it.** Iteration is live-site-only and undocumented, so prototype in DevTools first. An agent usually can't reach the authenticated site directly, so the loop is: hand the user a self-contained snippet to paste into the web inspector — an IIFE that `console.log`s what it finds and fails closed so it can't break the page — have them report back, iterate, then commit the finished script. Confirm across a few page types (a clipping, a note with backlinks, a note with no metadata). - `curl` against the live website may return a challenge page (HTTP 403). Probe site endpoints and JSON from the browser console with a same-origin `fetch`, not the shell. ## Scripting publish.js Two methods. Prefer the post-processor where it fits; reach for the observer when you must react to navigation or place content relative to late-rendering DOM. ### 1. The post-processor API Publish exposes a `publish` global with `registerMarkdownPostProcessor((el, ctx) => {...})`, mirroring the plugin API. It fires per rendered section; `ctx.frontmatter` is the note's parsed frontmatter as an object (no YAML parsing needed), and `ctx.containerEl` is the render container. This `publish` global is **undocumented** and not in the official help, so treat it as empirical: you can confirm it still exists with `typeof publish` / `console.log(publish)` in the console. ```js publish.registerMarkdownPostProcessor((el, ctx) => { const fm = el.querySelector("pre.frontmatter"); if (!fm || !ctx.frontmatter) return; // ctx.frontmatter.author, ctx.frontmatter.related, ctx.frontmatter.url, ... }); ``` `window.siteInfo` carries `{ uid, host, customurl, ... }`. The published-file index — needed to resolve a note title to its URL — is fetched same-origin from `https://${siteInfo.host}/cache/${siteInfo.uid}`. (`/cache.json` 404s.) **Caveat:** the post-processor can run on a render pass whose container is later discarded. Anything injected into the section's own DOM rides along, but `ctx.containerEl` is unreliable for finding elements rendered later (e.g. the backlinks footer) — for those, use the observer. ### 2. MutationObserver over the live DOM Publish re-renders the content pane on navigation without a full reload, so a load-time script misses later pages. Run an init on each mutation via a `MutationObserver` on `document.body`, gated by an idempotency marker (a class on processed elements) so it doesn't double-bind: ```js const SEEN = "mb-done"; new MutationObserver(() => { document.querySelectorAll(`.target:not(.${SEEN})`).forEach((el) => { el.classList.add(SEEN); // bind or inject }); }).observe(document.body, { childList: true, subtree: true }); ``` Use this to react to navigation, or to insert relative to elements that appear after the post-processor runs. To place a block just above the backlinks, watch for `.markdown-preview-sizer > .mod-footer` and `insertBefore` it (with an append fallback for notes that have no backlinks footer). Both methods build on one primitive: Publish emits each note's frontmatter as a hidden `pre.frontmatter.language-yaml` element. The post-processor hands it to you parsed as `ctx.frontmatter`; without the post-processor, read and parse the element's text. ## DOM gotchas - **Don't give injected links the `internal-link` class.** Publish's SPA resolver hijacks `.internal-link` for both click handling (rejecting hrefs it doesn't recognize with a "does not exist" page) and hover previews (a misleading "does not exist" popover). Give injected links a private class and your own `href`; add a `stopPropagation` on click as a guard. - **Use the site's custom domain for every link, never `publish.obsidian.md`.** Read it from `window.siteInfo.customurl` and build absolute URLs as `https://${siteInfo.customurl}/`. This applies to links injected by publish.js *and* to any URL handed to the user (e.g. a page to test) — a `publish.obsidian.md//...` link points at the wrong origin, where internal navigation and link previews break. - **URL encoding:** Publish encodes path spaces as `+`, not `%20`, and its router rejects `%20`. Build each path segment as `encodeURIComponent(segment).replace(/%20/g, "+")`. - **`