Skip to main content
This page explains how to customize the appearance and behavior of your Obsidian Publish site.

​
Site settings

Open site settings by clicking Publish changes in the Ribbon, then clicking Change site options (the cog icon).

​
General settings

SettingDescription
Site nameThe public title shown at the top of your site.
Homepage fileThe note that loads when a visitor opens your site’s root URL.
LogoA published image displayed as a site banner. The image must be published to your site.
Custom domainConfigure a custom domain for your site. See Custom domains.
Disallow search engine indexingAdds a robots.txt file to prevent search engines from crawling your site.

​
Appearance settings

SettingDescription
ThemeChoose Light, Dark, or Adapt to System.
Light/Dark toggleShow a toggle on your site that lets visitors switch between light and dark mode.

​
Reading experience

SettingDescription
Show hover previewShow a page preview when visitors hover over an internal link.
Hide page titleHide the inline title at the top of each note.
Readable line lengthLimit line width for comfortable reading.
Strict line breaksRender single line breaks as visible breaks.
Stack pagesEnable stacked tab navigation (sliding panels).

​
Components

SettingDescription
Show navigationDisplay the file explorer sidebar.
Show search barAdd a search bar to your site.
Show graph viewShow the graph view in the right sidebar.
Show table of contentsShow a table of contents for each page.
Show backlinksShow backlinks at the bottom of each page.

​
Customize navigation order

Navigation items are listed in published order by default. You can reorder them or hide specific notes and folders.
1

Open navigation settings

  1. Click Publish changes in the Ribbon.
  2. Click Change site options.
  3. Under Components settings, next to Customize navigation, click Manage.
2

Reorder items

In the Navigation preview, drag notes or folders to your preferred order. You can adjust note order within folders and folder order within other folders, but you cannot move notes between folders here.
3

Hide items

Right-click a note or folder and select Hide in navigation. The item is removed from the visible navigation while remaining published.To reveal hidden items, check Show hidden next to the Navigation Preview title.
4

Save changes

Click Done to apply your navigation changes to the live site.To restore defaults, click the Restore Default icon next to the relevant setting.

​
Custom CSS

Add a publish.css file to the root directory of your vault to apply custom styles to your site. 
/* publish.css — placed at the root of your vault */
body {
  --font-text-size: 18px;
}
Once the file exists, publish it from the Publish changes dialog — it won’t appear in the normal file explorer, but you can find it there.
CSS that works inside the Obsidian app may not behave the same way on Publish. For best results, develop CSS specifically for Publish. In general, styles that work in Reading view have the best chance of working on Publish.CSS variables for Publish are documented on the Obsidian developer docs.

​
Use a community theme

1

Locate the theme file

Open your vault’s settings folder (default: .obsidian), then open the themes folder.
2

Copy the theme CSS

Copy the CSS file for the theme you want to use.
3

Rename and place the file

Paste the file into the root folder of your vault and rename it to publish.css.
4

Publish the file

Open Publish changes and publish publish.css.
Many community themes use the Style Settings plugin for configuration. Style Settings does not work on Obsidian Publish.

​
Favicon

Publish accepts favicons using these naming conventions, where the number indicates pixel dimensions:
  • favicon-32.png
  • favicon-32x32.png
  • favicon.ico
For best cross-device coverage, provide multiple sizes: 
favicon-32x32.png
favicon-128x128.png
favicon-152x152.png
favicon-167x167.png
favicon-180x180.png
favicon-192x192.png
favicon-196x196.png
Favicons can be placed anywhere in your vault as long as they’re published.

​
Custom JavaScript

Add a publish.js file to the root of your vault to run custom scripts on your site.
Custom JavaScript via publish.js requires a custom domain. It will not run on the default publish.obsidian.md URL.
publish.js must be in the root directory of your vault, just like publish.css. Publish it from the Publish changes dialog. When a visitor shares a link to your site on social media, platforms like Twitter/X and Slack display a rich preview card. You can control what appears in these cards using note properties.
The meta tags set by these properties are only visible to web crawlers. Regular browsers see the normal page for performance reasons.

​
Custom description

Obsidian automatically generates a description from note content, but you can provide your own: 
---
description: An introduction to our solar system.
---
This overrides <meta name="description">, og:description, and twitter:description.

​
Custom image

Use image or cover (they’re identical — use only one) to set a custom preview image: 
---
cover: "Attachments/Cover image.png"
---
The image must be published to your site. The path is case-sensitive. You can also use an external URL: 
---
image: "https://example.com/cover%20image.png"
---
This overrides og:image.

​
SEO

Obsidian Publish sites are automatically optimized for search engines. A sitemap is available at /sitemap.xml and an RSS feed at /rss.xml.

​
Google Search Console

Register your site on Google Search Console to monitor search performance and indexing status.

​
Disable search engine indexing

To prevent search engines from crawling your site, enable Disallow search engine indexing in site settings. This adds a robots.txt file to your site.

​
Page metadata

Use note properties to customize per-page SEO metadata:
PropertyEffect
descriptionSets the page meta description and social preview description.
image / coverSets the social preview image (og:image).
permalinkSets a custom, permanent URL for the page.

​
Analytics

Analytics require a custom domain. They will not work on the default publish.obsidian.md URL.Before enabling analytics, check that your local laws and regulations allow visitor tracking. You may need to add a consent banner to your site.

​
Google Analytics

  1. Open Publish changes → Change site options.
  2. Under Other site settings, enter your tracking code in Google Analytics tracking code.
To use Google Tag Manager instead, add your GTM snippet via publish.js.

​
Plausible, Fathom, and other services

You can add any analytics service by injecting its script through publish.js. Replace yourdomain.com and the script URL with values from your analytics provider. 
var analyticsScript = document.createElement('script');
analyticsScript.defer = true;
analyticsScript.setAttribute('data-domain', 'yourdomain.com');
analyticsScript.src = 'https://plausible.io/js/plausible.js';
document.head.appendChild(analyticsScript);
If you’re not seeing analytics data, disable ad-blocking browser extensions such as uBlock Origin — they may block the tracking script during testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us