docs/obsidian-developer/Themes/Obsidian Publish themes/Best practices for Publish themes.md

metadata

cssClass: reference

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 */
}