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 caniuse.com 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.
Components
- 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.
Fonts
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 |
Sidebars
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 |
Navigation
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 |
Outline
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 |
Graph
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 |