Theme

The default theme ships inside the svedocs package. It uses Tailwind CSS v4 and framework CSS variables, so there is no separate theme package to install.

Styles

Import the theme stylesheet from the SvelteKit root layout:

Sveltesrc/routes/+layout.svelte
1<script>2  import 'svedocs/theme/styles.css';3</script>45<slot />

The stylesheet defines --sd-* tokens and uses data-theme for light and dark mode.

Form controls

The theme also exports basic form components for custom layouts, embedded tools, and interactive docs pages. They keep native Svelte ergonomics such as bind:value, forwarded DOM events, and standard form attributes.

Svelte
1<script lang="ts">2  import { Button, Checkbox, FormField, Input, Select, Textarea } from 'svedocs/theme';34  let email = '';5  let role = 'reader';6  let note = '';7  let updates = true;8</script>910<FormField label="Email" for="email" description="Used only for workspace notifications.">11  <Input id="email" type="email" bind:value={email} placeholder="you@example.com" />12</FormField>1314<FormField label="Role" for="role">15  <Select id="role" bind:value={role}>16    <option value="reader">Reader</option>17    <option value="editor">Editor</option>18  </Select>19</FormField>2021<FormField label="Notes" for="note">22  <Textarea id="note" bind:value={note} rows="4" />23</FormField>2425<Checkbox bind:checked={updates} label="Send release updates" />2627<Button variant="primary" type="submit">Save preferences</Button>

Available controls are FormField, Input, Textarea, Select, Checkbox, and Button. Input, Textarea, Select, Checkbox, and Button accept density="sm" | "md" | "lg". Button accepts variant="default" | "primary" | "ghost" | "danger".

Palette

For a quick brand color swap, set only theme.palette.accent:

TypeScriptsvedocs.config.ts
1import { defineConfig } from 'svedocs/config';23export default defineConfig({4  theme: {5    palette: {6      accent: 'sky'7    }8  }9});

TypeScriptsvedocs.config.ts
1import { defineConfig } from 'svedocs/config';23export default defineConfig({4  theme: {5    defaultMode: 'system',6    palette: {7      accent: 'emerald',8      neutral: 'zinc'9    },10    fonts: {11      sans: '"IBM Plex Sans", "Avenir Next", sans-serif',12      mono: '"JetBrains Mono", "SFMono-Regular", monospace',13      display: '"IBM Plex Sans", "Avenir Next", sans-serif'14    },15    radius: '2px',16    codeTheme: {17      light: 'light-plus',18      dark: 'dark-plus'19    },20    code: {21      copyButton: true22    },23    brand: {24      label: 'svedocs',25      href: '/',26      mark: 'pixel'27    },28    nav: [29      { label: 'Docs', href: '/docs' },30      { label: 'Configuration', href: '/docs/configuration' },31      { label: 'API', href: '/docs/reference/api' }32    ],33    social: [34      { label: 'GitHub', href: 'https://github.com/svedocs/svedocs', external: true }35    ],36    footer: {37      text: 'MIT licensed.',38      links: [{ label: 'Cloudflare', href: '/docs/integrations/cloudflare' }]39    },40    home: {41      kicker: 'Edge-first Svelte docs',42      primaryAction: { label: 'Read docs', href: '/docs' },43      secondaryAction: { label: 'Configure', href: '/docs/configuration' },44      visual: { type: 'pixel' }45    }46  }47});

palette.accent accepts a built-in color name such as emerald, teal, sky, indigo, rose, or amber. You can also pass any CSS color value, including #0ea5e9, hsl(221 83% 53%), or oklch(62% 0.18 250).

home.visual can stay as the built-in pixel module or point at a project image with { type: 'image', src: '/hero.png', alt: 'Preview' }.

Theme slots

DocsApp exposes named slots for changing parts of the page without rebuilding its routing, metadata, header, footer, search, Ask AI, or docs navigation.

Sveltesrc/routes/+page.svelte
1<script lang="ts">2  import { DocsApp } from 'svedocs/theme';3  import components from 'virtual:svedocs/components';4  import layouts from 'virtual:svedocs/layouts';5  import loadSearch from 'virtual:svedocs/search-loader';67  export let data;8</script>910<DocsApp11  page={data.page}12  pages={data.pages}13  tree={data.tree}14  search={data.search}15  config={data.config}16  {components}17  {layouts}18  {loadSearch}19>20  <div slot="background" class="brand-background"></div>21</DocsApp>

The background slot replaces the built-in grid layer on the homepage, single pages, and documentation articles. It is rendered as an aria-hidden decorative layer with pointer events disabled.

Homepage-specific slots let you replace smaller regions:

Sveltesrc/routes/+page.svelte
1<script lang="ts">2  import { resolveLocalizedHref } from 'svedocs/theme/headless';3</script>45<DocsApp6  page={data.page}7  pages={data.pages}8  tree={data.tree}9  search={data.search}10  config={data.config}11  {components}12  {layouts}13  {loadSearch}14>15  <div slot="home-hero-visual" class="product-orbit" aria-hidden="true"></div>1617  <section slot="home-features" let:cards let:context class="feature-strip">18    <h2>{context.t('home.features')}</h2>19    {#each cards as card}20      <a href={card.href}>{card.title}</a>21    {/each}22  </section>23</DocsApp>

Use home-hero-visual to replace the pixel hero effect or configured hero image. Use home-features to replace the default feature blocks. The slot receives the generated cards array so custom blocks can reuse the same documentation links. It also receives context, so custom UI can call context.t(...), read context.localeCode, or use context.messages.

To replace the entire landing content while preserving the svedocs header and footer, use landing:

Sveltesrc/routes/+page.svelte
1<DocsApp2  page={data.page}3  pages={data.pages}4  tree={data.tree}5  search={data.search}6  config={data.config}7  {components}8  {layouts}9  {loadSearch}10>11  <section slot="landing" let:page let:context class="custom-landing">12    <h1>{page.title}</h1>13    <p>{page.description}</p>14    <a href={resolveLocalizedHref('/docs', context)}>15      {context.t('home.primaryAction')}16    </a>17  </section>18</DocsApp>

The theme still provides the main#content wrapper for the landing slot, so the skip link and page semantics remain intact.

In custom landing pages and replacement components, use context.t('message.key') instead of hard-coding interface text. Add built-in or project-specific keys to i18n.messages; custom components receive the catalog for the active locale. Use context.localeCode for filtering data and context.languageTag for HTML attributes or locale-sensitive formatting. See Internationalization for the complete setup.

Documentation articles also expose doc-header when you only need to replace the title and breadcrumb area:

Svelte
1<DocsApp2  page={data.page}3  pages={data.pages}4  tree={data.tree}5  search={data.search}6  config={data.config}7  {components}8  {layouts}9  {loadSearch}10>11  <header slot="doc-header" let:page let:breadcrumbs class="article-hero">12    <nav>13      {#each breadcrumbs as item}14        <a href={item.path}>{item.label}</a>15      {/each}16    </nav>17    <h1>{page.title}</h1>18  </header>19</DocsApp>

Theme development

Choose the level of customization that matches the change:

Layer	Use it when
Theme tokens	You like the default components and only need brand color, fonts, radius, navigation, homepage, or code settings.
Component replacement	You want to keep the svedocs route shell and replace one or more visual components.
Headless composition	You want to own the markup and CSS while reusing search, Ask AI, ToC, theme mode, mobile nav, and copy behavior.

The default CSS is optional:

Import	Result
svedocs/theme/styles.css	Full bundled visual theme.
svedocs/theme/base.css	Minimal reset, accessibility helpers, and prose/code structure.
No theme CSS	Your app or theme package owns all styles.

Keep configuration values in svedocs.config.ts. Put Svelte component imports in the Vite plugin because component paths are build-time imports and should not be serialized into the content config.

Register replacement components in the Vite plugin:

TypeScriptvite.config.ts
1svedocs({2  theme: {3    components: {4      Navbar: '$lib/theme/Navbar.svelte',5      Article: '$lib/theme/Article.svelte',6      Search: '$lib/theme/Search.svelte',7      AskAi: '$lib/theme/AskAi.svelte'8    }9  }10});

Generated route files import virtual:svedocs/theme-components and pass it into DocsApp, so overrides apply without changing every route:

Sveltesrc/routes/+page.svelte
1<script lang="ts">2  import { DocsApp } from 'svedocs/theme';3  import components from 'virtual:svedocs/components';4  import layouts from 'virtual:svedocs/layouts';5  import themeComponents from 'virtual:svedocs/theme-components';6  import loadSearch from 'virtual:svedocs/search-loader';78  export let data;9</script>1011<DocsApp12  page={data.page}13  pages={data.pages}14  tree={data.tree}15  search={data.search}16  config={data.config}17  {components}18  {layouts}19  {themeComponents}20  {loadSearch}21/>

Replacement components receive typed props from svedocs/theme/types. The component map supports Root, Layout, Docs, DocsShell, Page, PageShell, Home, Error, Header, Navbar, Brand, TopNav, MobileNav, SocialNav, Sidebar, Article, Toc, Search, AskAi, Footer, FooterLinks, ThemeToggle, PageTools, and RenderError. See Components for the full per-component props.

Sveltesrc/lib/theme/Navbar.svelte
1<script lang="ts">2  import type { SvedocsNavbarProps } from 'svedocs/theme/types';34  export let context: SvedocsNavbarProps['context'];5</script>67<header class="brand-nav">8  <a href={context.config.theme.brand.href}>{context.config.theme.brand.label}</a>9</header>

Use svedocs/theme/headless when you want the framework behavior without the default UI. It exports controllers for theme context, search, Ask AI, ToC tracking, theme mode, mobile nav, page tools, and code-copy behavior.

Sveltesrc/lib/theme/Search.svelte
1<script lang="ts">2  import { createSearchController } from 'svedocs/theme/headless';3  import type { SvedocsSearchProps } from 'svedocs/theme/types';45  export let records: SvedocsSearchProps['records'] = [];6  const search = createSearchController({ records });7</script>89<button type="button" on:click={search.show}>Search</button>

When writing replacement components:

• Keep normal landmarks such as header, nav, main, article, aside, and footer.
• Render content for compiled .svx / .mdx pages and fall back to page.html when no content component exists.
• Pass themeComponents to nested default components when you still compose part of the bundled theme.
• If you replace Root, Docs, Page, Home, or Error, keep passing pages, tree, search, config, and loadSearch into the theme context or nested default components so sidebar highlighting, mobile navigation, search, and Ask AI keep working.
• Replace Layout, DocsShell, or PageShell for layout geometry changes before replacing the larger Root, Docs, Page, or Error components.
• Use loadSearch for large sites instead of forcing all search records into the first route payload.
• Trigger the default search and Ask AI panels with svedocs:open-search and svedocs:open-ai events when you build custom command buttons.

Markdown output still includes stable sd-* structure classes for prose, headings, and code blocks so default styles and custom styles can target the same markup. Set theme.code.copyButton: false if your theme renders its own copy control.

Generated templates include src/routes/+error.svelte. Register theme.components.Error to replace full-route error pages, and register theme.components.RenderError to replace local error-boundary UI inside article content, layout regions, navigation, and tools. The generated error route catches failures in a custom Error component and falls back to the bundled ErrorPage.

Theme packages can be ordinary Svelte libraries. Export Svelte components from the package, document the expected svedocs peer version, and have users register the package component paths in svedocs({ theme: { components } }).

Interaction

Built-in theme behavior includes:

• Search dialog with keyboard focus management.
• Ask AI panel with JSON and event-stream responses.
• Command palette for docs, search, and Ask AI entry points.
• Recursive sidebar with collapsed groups and locale-scoped trees.
• Mobile menu state with transition.
• ToC highlighting based on the active heading.
• Code block toolbar with copy support.
• prefers-reduced-motion compatible transitions.

Single pages

Content under content/pages renders through the built-in single-page template by default. Use layout: home for the homepage, layout: page for the built-in page template, or a registered custom layout name for project-specific pages.

Markdown
1---2title: Changelog3description: Product updates rendered with the single-page template.4---56# Changelog

Custom layouts

Register named layouts in the Vite plugin:

TypeScriptvite.config.ts
1svedocs({2  layouts: {3    feature: '$lib/FeatureLayout.svelte'4  }5});

Then select a layout in frontmatter:

Markdown
1---2title: Feature Page3layout: feature4---

Layouts receive the same data as default pages, so a custom single page can still use the page list, search records, SEO metadata, and surrounding site UI.