Site Settings

Overview

Site settings control global behaviors across your entire documentation site. These settings affect features like pagination, view transitions, copy-to-clipboard buttons, and the base route path. They are configured in a single TypeScript file and apply to all pages uniformly.

Config File Location

The site settings configuration lives at:

src/docs/config/siteSettings.ts

This file exports an object containing all global settings for your documentation site.

Basic Configuration

Here is the default site settings configuration:

// src/docs/config/siteSettings.ts

export interface SiteSettings {
  copyLinkButtons: boolean;
  useViewTransitions: boolean;
  pagination: boolean;
  docsRoute: string;
}

export const siteSettings: SiteSettings = {
  copyLinkButtons: true,
  useViewTransitions: false,
  pagination: true,
  docsRoute: "docs",
};

Available Settings

copyLinkButtons

Controls whether copy-to-clipboard buttons appear on headings throughout the documentation. When enabled, hovering over any heading (h2 through h6) reveals a small link icon. Clicking the icon copies a direct URL to that heading to the clipboard.

export const siteSettings = {
  copyLinkButtons: true,
};

When Enabled (true)

• A link icon appears on hover for all headings h2 through h6
• Clicking the icon copies the full URL with the heading anchor (e.g., https://docs.example.com/docs/guide#installation)
• A brief confirmation tooltip appears after copying
• The URL is updated in the browser address bar

When Disabled (false)

• No link icons appear on headings
• Headings still have id attributes for direct linking, but there is no visual affordance for copying
• Users can still manually copy the URL from the browser address bar

useViewTransitions

Enables the View Transitions API for smooth animated page transitions. When enabled, navigating between documentation pages triggers a crossfade animation instead of a full page reload.

export const siteSettings = {
  useViewTransitions: false,
};

When Enabled (true)

• Page navigations trigger a smooth crossfade animation
• The sidebar and navigation bar persist visually during transitions
• Scroll position is reset to the top of the new page
• The browser’s back and forward buttons work with animated transitions

When Disabled (false)

• Standard full-page navigation is used
• Each page navigation triggers a complete page load
• This is the more compatible option for older browsers

pagination

Controls whether previous/next navigation links appear at the bottom of each documentation page. These links help readers move sequentially through the documentation.

export const siteSettings = {
  pagination: true,
};

When Enabled (true)

• “Previous” and “Next” links appear at the bottom of each page
• Links are determined by the sidebar order within the current section
• The first page in a section shows only “Next”
• The last page in a section shows only “Previous”
• Link labels display the target page’s sidebar label

When Disabled (false)

• No pagination links appear at the bottom of pages
• Readers must use the sidebar or browser navigation to move between pages

docsRoute

Defines the base URL path segment for all documentation pages. By default, documentation pages are served under /docs/. Changing this value moves the entire documentation to a different URL prefix.

export const siteSettings = {
  docsRoute: "docs",
};

Examples

Changing the Route

To change the documentation base route:

Settings Summary

TypeScript Support

The SiteSettings interface provides complete type checking for all settings. If you add an unrecognized property or use an incorrect type, your editor and the TypeScript compiler will report an error.

export const siteSettings: SiteSettings = {
  copyLinkButtons: true,
  useViewTransitions: false,
  pagination: true,
  docsRoute: "docs",
  // unknownSetting: true,  // TypeScript error: property does not exist
};

Environment-Specific Settings

If you need different settings for development and production, you can use environment checks:

const isDev = import.meta.env.DEV;

export const siteSettings: SiteSettings = {
  copyLinkButtons: true,
  useViewTransitions: !isDev, // Only enable in production
  pagination: true,
  docsRoute: "docs",
};

This pattern is useful for features like view transitions that you may want to test only in production builds, or for enabling verbose logging during development.