Publish Theming Guide

Important! On February 23rd 2023 we will be lightly updating the design of Publish sites to the same standard as Obsidian 1.0.

We’ve made efforts to make sure this change will not disrupt the look of most Publish sites. However, if your site has a highly customized theme or CSS, you may notice some changes.

With this new version of Publish, we’re also making it easier to customize the CSS for your site. You can learn more from the guide below.

See related 1.0 Theme Migration Guide.

Publish Theming Guide

Obsidian Publish allows you to customize the look of your site using CSS. This guide explains how you can create a custom Publish theme.

Create and enable Publish themes

Create a Publish theme

To create a Publish theme, add your custom CSS rules to a file named publish.css. See the section below for a list of CSS variables you can use to customize your site.

The contents of the publish.css file can be as simple as:

.published-container {
  --readable-width: 1000px;
  --bold-weight: 600;
  /* ... CSS variables */
.theme-light {
  --background-primary: #ebf2ff;
  /* ... CSS color variables for light mode */
.theme-dark {
  --background-primary: #1f2a3f;
  /* ... CSS color variables for dark mode */

Enable a Publish theme

To enable a custom theme for your Publish site, add the publish.css file to your vault, and publish it as you would any other file. Learn more about customizing your Publish site.

Best practices for Publish themes

Obsidian App and Obsidian Publish are different contexts

Obsidian Publish shares common code and UI principles with Obsidian App, but also has some important differences that you should consider when creating themes. A few rules of thumb to keep in mind:

  • Avoid complex selectors, use the available CSS variables instead.
  • Avoid including CSS selectors and rules that are specific to Obsidian App.
  • Keep CSS file size small so it loads fast for visitors.
  • Consider compatibility across browsers and screen sizes.

App-specific and Publish-specific CSS rules

While Obsidian App and Obsidian Publish share some common code, most App themes are designed to target CSS classes that are not present in the Publish context. For this reason, we recommend building Publish themes from the ground up, to minimize the amount of unnecessary code.

File size

Obsidian App themes are stored locally on the user’s device, whereas Obsidian Publish themes are loaded each time a user vists the site. For this reason, Obsidian Publish themes should be mindful of file size.

Keeping your theme file small will avoid flashes of unstyled content, and load faster on a variety of devices and internet connections. Ideally your publish.css file should be as small as possible.

In the App context it is acceptable to embed fonts and images in the CSS file using base64 encoding. In the Publish context, we recommend that you avoid this approach, especially if it leads to larger file sizes (multiple megabytes) that may block rendering when a visitor accesses the site.

Browser compatibility

Visitors to Publish sites may use older browsers that are not compatible with new CSS features. For this reason we recommend being conservative with advanced CSS features in the Publish context. This is in contrast to Obsidian App themes which target a narrow scope of rendering engines (recent versions of Chromium/Blink) that support newer browser features. Try searching to see which CSS features are broadly available across browsers.

Small screens and mobile devices

Obsidian Publish has two breakpoints by default:

Breakpoint Device Effect
1000px Tablet Right sidebar is hidden
750px Mobile Left and right sidebars are hidden. If enabled, navigation is accessible via hamburger menu in the top left corner

You can target these devices using CSS. Any rules defined outside of the @media query will apply to all devices.

@media screen and (min-width: 1000px) {
  /* ... rules and variables for screens larger than tablet */
@media screen and (max-width: 1000px) {
  /* ... rules and variables for tablet devices and smaller */
@media screen and (max-width: 750px) {
  /* ... rules and variables for mobile devices and smaller */

Optional UI features and components

The following elements can be turned on or off in the Publish site settings and influence the layout of the site.

Reading experience

  • Readable line length sets a maximum width for notes and centers the content on wide screens.
  • Theme toggle displays a switch for light/dark mode.
  • Stacked notes enables notes to stack and scroll horizontally when links are clicked, similar to Tab stacks in the Obsidian App.


  • Navigation adds a left sidebar with a list of folders and files.
  • Search displays a search input field, it may be positioned in the left sidebar, right sidebar or top navigation depending on which UI elements are active.
  • Backlinks displays a list of backlinks at the bottom of the page.
  • Graph displays the local graph in the right sidebar.
  • Table of contents displays an outline of headings in the current page in the right sidebar.

CSS variables

Theming for Obsidian Publish is made simple with CSS variables. Learn more about CSS variables and how to use them.

To view the list of all the Obsidian CSS variables available to customize your theme, see the top of the app.css file.

Inherited CSS variables

Obsidian Publish inherits CSS variables from the Obsidian App theme. This makes it easy to convert your Obsidian App theme into a Publish theme. Variables inherited from the Obsidian App fall into the following categories.

Defined on the body element:

  • Components such as inputs, buttons, and popovers
  • Content types such as blockquotes, callouts, code blocks, syntax highlighting, embeds, footnotes, headings, links, lists, tables, tags, and task lists

Defined on the .theme-light and .theme-dark classes:

  • Colors for light and dark mode backgrounds, borders, text and accents

Publish-specific CSS variables

The following CSS variables can be defined on the .published-container element.


To load remote fonts we recommend using CSS with @import or defining your fonts with @font-face and an absolute URL. Learn more.

Variable Description
--font-text-size Font size for page text
--font-text-theme Font family for page text
--font-monospace-theme Font family for code
--font-interface-theme Font family for interface elements such as navigation
--font-mermaid Font family for Mermaid diagrams

Site header, site logo, and site name

The site header contains the site logo (if added in Publish settings), the site name, and the mobile hamburger menu if navigation is turned on.

The site header appears as a horizontal header at the top of the page on mobile devices and when navigation is turned off. When navigation is turned on in Publish settings, the site name and logo appear in the left sidebar.

Variable Description
--logo-width Logo default width
--logo-height Logo default height
--logo-max-width Logo max width
--logo-max-height Logo max height
--logo-radius Logo corner radius
--header-height Height of the site header
--site-name-color Site name color
--site-name-color-hover Site name hovered color
--site-name-font Site name font family
--site-name-size Site name font size
--site-name-weight Site name font weight
--site-menu-icon-color Mobile menu icon color
--site-menu-icon-color-hover Mobile menu hovered icon color
--site-menu-icon-size Mobile menu icon size

Page width and padding

Variable Description
--page-width Width of a note when readable line width is on
--page-padding Padding around a note

Page title

The note title displayed at the top of the page. This title can be hidden in the Publish site settings using the “Hide page title” option.

Variable Description
--page-title-color Font color
--page-title-font Font family
--page-title-line-height Line height
--page-title-size Font size
--page-title-style Font style, e.g. normal or italic
--page-title-variant Font variant
--page-title-weight Font weight


The left sidebar is present when Navigation is turned on. The right sidebar is present when the Graph and/or Table of Contents elements are turned on. When these elements are turned off, the following variables have no effect.

Variable Description
--sidebar-left-width Width of the left sidebar
--sidebar-left-background Background color of left sidebar
--sidebar-left-border-width Right border width of left sidebar
--sidebar-left-border-color Right border color of left sidebar
--sidebar-right-width Width of the right sidebar
--sidebar-right-background Background color of right sidebar
--sidebar-right-border-width Left border width of right sidebar
--sidebar-right-border-color Left border color of right sidebar


When activated in Publish settings, navigation is placed in the left sidebar and can be styled with the following variables. Top-level items and folders can be treated differently than nested items.

Variable Description
--nav-collapse-icon-color Collapse icon color
--nav-collapse-icon-color-hover Collapse icon color (hovered)
--nav-parent-item-color Font color for folders and top-level items
--nav-parent-item-color-active Font color for active top-level items
--nav-parent-item-weight Font weight for top-level items
--nav-item-color Font color for nested items
--nav-item-color-hover Font color for hovered nested items
--nav-item-color-active Font color for active nested items
--nav-item-border-color Border color for nested items
--nav-item-border-color-hover Border color for hovered nested items
--nav-item-border-color-active Border color for active nested items
--nav-item-weight-active Font weight for active nested items


When activated in Publish settings, a table of contents is displayed in the right sidebar showing a navigable list of headings on the page.

Variable Description
--outline-heading-color Font color for inactive headings
--outline-heading-color-hover Font color for hovered heading
--outline-heading-color-active Font color for active heading
--outline-heading-weight-active Font weight for active heading


The graph component can be turned on in Publish settings. More graph CSS variables for node and line colors are present in the inherited CSS.

Variable Description
--graph-height Height of the graph component

Component titles

Styles for the title above components such as Backlinks, Graph, Table of contents, when these components are turned on in the site settings.

Variable Description
--component-title-color Font color
--component-title-font Font family
--component-title-size Font size
--component-title-style Font style, e.g. normal or italic
--component-title-transform Text transform, e.g. uppercase
--component-title-variant Font variant
--component-title-weight Font weight