主题

默认主题内置在 svedocs 包里。它使用 Tailwind CSS v4 和框架 CSS 变量，不需要安装额外主题包。

样式

在 SvelteKit 根布局里导入主题样式：

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

这份样式定义了 --sd-* 变量，并通过 data-theme 切换明暗模式。

表单控件

主题也导出了一组基础表单组件，适合自定义布局、嵌入式工具和交互式文档页使用。它们保留 Svelte 的原生使用习惯，例如 bind:value、DOM 事件转发和标准表单属性。

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="邮箱" for="email" description="仅用于工作区通知。">11  <Input id="email" type="email" bind:value={email} placeholder="you@example.com" />12</FormField>1314<FormField label="角色" for="role">15  <Select id="role" bind:value={role}>16    <option value="reader">读者</option>17    <option value="editor">编辑者</option>18  </Select>19</FormField>2021<FormField label="备注" for="note">22  <Textarea id="note" bind:value={note} rows="4" />23</FormField>2425<Checkbox bind:checked={updates} label="接收版本更新" />2627<Button variant="primary" type="submit">保存偏好</Button>

可用控件包括 FormField、Input、Textarea、Select、Checkbox 和 Button。Input、Textarea、Select、Checkbox、Button 支持 density="sm" | "md" | "lg"；Button 支持 variant="default" | "primary" | "ghost" | "danger"。

调色板

只想快速换品牌主题色时，只配置 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: '文档', href: '/docs/zh' },30      { label: '配置', href: '/docs/zh/configuration' },31      { label: '参考', href: '/docs/zh/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/zh/integrations/cloudflare' }]39    },40    home: {41      kicker: '边缘优先的 Svelte 文档站',42      primaryAction: { label: '阅读文档', href: '/docs/zh' },43      secondaryAction: { label: '去配置', href: '/docs/zh/configuration' },44      visual: { type: 'pixel' }45    }46  }47});

palette.accent 可以使用 emerald、teal、sky、indigo、rose 或 amber 等内置颜色名，也可以直接填写 #0ea5e9、hsl(221 83% 53%)、oklch(62% 0.18 250) 等任意 CSS 颜色值。

home.visual 可以继续使用内置的像素效果，也可以指向项目中的图片：{ type: 'image', src: '/hero.png', alt: 'Preview' }。

主题插槽

DocsApp 提供命名插槽，可以只替换页面中的某个区域，不必重新实现路由、元数据、页头、页脚、搜索、Ask AI 和文档导航。

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>

background 插槽会替换首页、普通单页和文档文章中的内置格子背景。它会作为 aria-hidden 的装饰层渲染，并禁用指针事件。

首页还提供更细粒度的插槽：

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>

用 home-hero-visual 替换首页主视觉中的像素效果或配置图片，用 home-features 替换默认的功能介绍区。home-features 会收到生成后的 cards 数组，方便自定义内容复用同一组文档链接；它也会收到 context，可以调用 context.t(...)、读取 context.localeCode 或使用 context.messages。

如果要替换首页的全部内容，但保留 svedocs 的页头和页脚，可以使用 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>

landing 插槽外层仍由主题提供 main#content，因此跳转到正文的无障碍链接和页面语义不会丢失。

在自定义首页和替换组件中，使用 context.t('message.key') 读取界面文案，不要把文字写死。可以在 i18n.messages 中添加内建或项目自定义的键，自定义组件会收到当前语言的文案。过滤数据时使用 context.localeCode，设置 HTML 属性或按语言格式化数据时使用 context.languageTag。完整配置见多语言。

文档文章也提供 doc-header，适合只替换标题和面包屑区域：

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>

主题开发

根据改动范围选择合适的定制方式：

层级	适合场景
主题变量	保留默认组件，只调整品牌色、字体、圆角、导航、首页或代码块设置。
组件替换	你想保留 svedocs 路由壳层，但替换一个或多个视觉组件。
无样式组合	完全接管 HTML 结构和 CSS，同时复用搜索、Ask AI、目录高亮、明暗模式、移动导航和复制行为。

默认 CSS 是可选的：

导入方式	结果
svedocs/theme/styles.css	完整内置视觉主题。
svedocs/theme/base.css	最小样式重置、无障碍基础样式，以及正文和代码结构。
不导入主题 CSS	应用或主题包完全接管所有样式。

普通配置继续放在 svedocs.config.ts。Svelte 组件路径则放在 Vite 插件中，因为它们需要在构建时导入，不应被序列化进内容配置。

在 Vite 插件里注册替换组件：

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});

生成的路由会导入 virtual:svedocs/theme-components 并传给 DocsApp，所以不用逐个页面手动接线：

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

替换组件可以从 svedocs/theme/types 获取属性类型。可替换组件包括 Root、Layout、Docs、DocsShell、Page、PageShell、Home、Error、Header、Navbar、Brand、TopNav、MobileNav、SocialNav、Sidebar、Article、Toc、Search、AskAi、Footer、FooterLinks、ThemeToggle、PageTools 和 RenderError。各组件的完整属性见组件。

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>

如果只想复用交互逻辑、不使用默认界面，可以从 svedocs/theme/headless 引入控制器。其中包含主题上下文、搜索、Ask AI、目录高亮、明暗模式、移动导航、页面工具和代码复制等逻辑。

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}>搜索</button>

编写替换组件时：

• 保留 header、nav、main、article、aside、footer 等标准语义区域。
• 对 .svx / .mdx 页面渲染 content，没有内容组件时回退到 page.html。
• 仍然组合部分默认组件时，把 themeComponents 继续传给嵌套组件。
• 如果替换 Root、Docs、Page、Home 或 Error，继续把 pages、tree、search、config 和 loadSearch 传入主题上下文或嵌套的默认组件，这样侧栏高亮、移动导航、搜索和 Ask AI 才能保持联动。
• 只调整布局几何结构时，优先替换 Layout、DocsShell 或 PageShell，再考虑替换更大的 Root、Docs、Page 或 Error。
• 大型站点优先使用 loadSearch，避免把所有搜索记录都放进首屏路由数据。
• 自定义命令按钮可以用 svedocs:open-search 和 svedocs:open-ai 事件打开默认搜索和 Ask AI 面板。

Markdown 输出会保留稳定的 sd-* 结构类名，默认主题和自定义主题都可以针对同一套正文、标题和代码结构编写样式。如果主题自己渲染复制按钮，可以设置 theme.code.copyButton: false。

生成模板已经包含 src/routes/+error.svelte。注册 theme.components.Error 可以替换完整路由的错误页；注册 theme.components.RenderError 可以替换文章内容、布局区域、导航和工具中的局部错误提示。生成的错误路由会捕获自定义 Error 组件自身的异常，并改用内置 ErrorPage。

主题包可以是普通的 Svelte 库。从包中导出组件，声明兼容的 svedocs peer dependency 版本，再让使用者在 svedocs({ theme: { components } }) 中注册对应的组件路径即可。

交互能力

默认主题包括：

• 带键盘焦点管理的搜索弹窗。
• 支持 JSON 和事件流响应的 Ask AI 面板。
• 文档、搜索、Ask AI 入口工具栏。
• 可折叠的递归侧栏，以及按语言过滤的导航树。
• 移动端菜单状态和过渡。
• 根据当前位置高亮目录标题。
• 带复制按钮的代码块工具条。
• 兼容 prefers-reduced-motion 的过渡。

单页

content/pages 下的内容默认用内置单页模板渲染。首页使用 layout: home，普通单页使用 layout: page，也可以使用注册过的自定义布局名。

Markdown
1---2title: 更新日志3description: 使用单页模板展示产品更新。4---56# 更新日志

自定义布局

在 Vite 插件里注册命名布局：

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

然后在 frontmatter 里选择它：

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

布局组件会收到与默认页面相同的数据，因此自定义单页仍然可以使用页面列表、搜索记录、SEO 元数据和站点外壳。