Global settings

Reference for common site, navigation, search, and discovery settings in publier.config.yaml.

The publier.config.yaml file at your project root controls site-wide settings — name, navigation, search, analytics, fonts, and snippets.

Full example

site:
  name: My Docs
  url: https://docs.example.com

nav:
  default:
    links:
      - label: GitHub
        href: https://github.com/my-org/my-docs
        external: true

sidebar:
  defaultOpenLevel: 2

search:
  enabled: true

llms:
  enabled: true

snippets:
  directory: src/content/snippets

Site

Navigation

GitHub links auto-render as icon buttons. Other external links render as text. See Navigation for variants and pathRules.

Sidebar

sidebar.defaultOpenLevel is a non-negative integer: 1 opens top-level folders, 0 collapses folders by default, and 2 opens two levels. Folder-specific collapsed values in docs.sidebar.meta override that default. On render and navigation, the current page’s folder and ancestors open even if configured collapsed; readers can still collapse them.

Appearance

appearance:
  default: system
  strict: false

appearance.default accepts system, light, or dark; the defaults are system and strict: false. Readers can choose light, dark, or auto, with explicit choices saved in localStorage across navigation and reloads. Auto returns to the configured default and follows the OS only when that default is system. With strict: true, the switch is hidden and stored reader choices are ignored; strict system mode still follows OS changes.

Documentation sections

Group documentation by content-folder paths, including nested paths:

docs:
  tabSections: [platform, platform/api, integrations]

Add a landing page such as src/content/docs/platform/index.mdx for each section. Its title becomes the label in breadcrumbs and in the header’s fallback section links. The default docs route shows only the current section’s sidebar. When no docs navigation variant is configured, All documentation in the header returns to the docs index, sections without a landing page link to their first available page, and empty sections are omitted. Configure nav.docs.tabs for your own section labels and destinations; the sidebar does not repeat the header’s section selector.

The longest matching path owns each article, respecting whole path segments. In this example, /docs/platform/api/check belongs to platform/api, while the parent platform sidebar excludes that API section. /docs/platform/apiary still belongs to platform. Since shell 4.3.2/native 6.0.1, local /docs/ destinations in nav.docs.products[].tabs automatically supply these scopes; you do not need to repeat their paths in tabSections.

Since shell 4.4.0/native 7.0.0, a scoped sidebar removes the folder hierarchy through the selected section. For platform/api, its pages and child groups appear directly, without enclosing Platform or API groups. A visible platform/api/index.mdx supplies an ordinary top-level Overview link to /docs/platform/api, marked as the current page on that landing page. If the index is missing or hidden from the sidebar, no Overview link is added. Every remaining page keeps its full destination URL, so selecting Overview or an article stays within the section on desktop and mobile.

Keep sidebar metadata keyed by the complete content-folder path: for example, docs.sidebar.meta.platform/api/reference still controls the Reference group inside the API section. Scoping preserves metadata labels, ordering, and explicit collapsed settings. sidebar.defaultOpenLevel continues to use the original folder depth before enclosing folders are removed; scoping does not automatically expand groups that were deeper in the full hierarchy. Without a selected scope, the sidebar hierarchy is unchanged.

The shared layout includes a keyboard-accessible navigation menu on small screens, a collapsible On this page list, and search at every screen size. Search indexes article content, excluding navigation and breadcrumbs.

Custom routes can render SectionSwitcher from @publier/shell/components. Pass sections as an array of { label, href } and currentPath as the current URL pathname. Its links support arrow keys and Escape.

Search

The shortcut is fixed at Cmd/Ctrl + K; search.hotkey is not applied by the current shell. To disable the built-in dialog and its keyboard handler, use the existing docsShell({ search: false }) integration option. That option does not hide the header trigger; the YAML setting controls that separately. See Search.

LLMs

Groups use the first URL path segment; the homepage is pages. These groups are independent of Astro content collections. Error routes and noindex pages are excluded. The summary comes from site.description. Tools that support the llms.txt convention can use this index; it does not guarantee indexing or citations. See AI features for current capabilities.

Snippets

See the Snippets guide for usage.

Logo and favicon

site:
  logo:
    light: /logo-light.svg  # shown in light mode
    dark: /logo-dark.svg    # shown in dark mode
  favicon: /favicon.ico

Paths are relative to public/.

Edit links

There is no editLink.baseUrl configuration in the current framework. Add an ordinary source link to your page content or a custom layout when readers need to propose edits.

Pages

The pages: YAML flags are not consumed by the current shell’s route planner. They neither create nor suppress routes, and do not remove links from navigation, sitemap, search, or feeds.

The shell injects docs, blog, and changelog routes only when the corresponding content directories contain entries. Its existing docsShell({ routes: ... }) integration option controls those default routes, the default 404, and RSS. Company pages come from src/pages/; status and knowledge-base routes are not automatically supplied. See Pages for the supported route controls and current limits.