Default theme

安装

npm install --save @sveltepress/theme-default
sh

在 vite.config.(js|ts) 中配置

vite.config.(js|ts)
+
-
+
+
+
import {  } from '@sveltepress/theme-default' 
import {  } from '@sveltepress/vite'

import {  } from 'vite'

const  = ({
  : [
    ({/** 配置 */}), 
    ({ 
      : (/** 主题配置 */) 
    }) 
  ],
})

export default 
ts

主题配置

类型一览

类型一览
/// <reference types="vite/client" />
/// <reference types="@sveltepress/vite/types" />
/// <reference types="@sveltejs/kit/vite" />

declare module 'virtual:sveltepress/theme-default' {
  import type {  } from '@sveltepress/docsearch/types'
  import type {  } from '@sveltepress/twoslash'
  import type {  } from '@sveltepress/vite'
  import type {  } from '@vite-pwa/sveltekit'
  import type {  } from 'shiki'
  import type {  } from 'shiki/langs'
  import type {  } from 'svelte'

  export interface WithTitle {
    ?: string
  }

  export interface LinkItem extends WithTitle {
    ?: string
    ?: string
    ?: boolean
    ?: boolean
    ?: LinkItem[]
  }

  export interface AutoSidebarOptions {
    /**
     * Enable auto-generated sidebar
     */
    : boolean
    /**
     * Routes directory, default 'src/routes'
     */
    ?: string
    /**
     * Root paths to generate sidebar for, e.g. ['/guide/', '/reference/']
     * If not specified, auto-detect from top-level route directories
     */
    ?: string[]
  }

  export interface DefaultThemeOptions {
    ?: <LinkItem>
    ?: string
    ?: string
    ?: <string, LinkItem[]> | AutoSidebarOptions
    ?: string
    ?: string
    ?: string
    ?:  & {
      ?: string
      /**
       * Which prerendered HTML pages to put in the Workbox precache.
       *
       * Default `false` only precaches the homepage so service-worker
       * install/update stays fast on sites with many versions and locales.
       *
       * - `false`: homepage only
       * - `true`: all prerendered HTML (historical versions are still ignored)
       * - `string[]`: URL prefixes, e.g. `['/zh/', '/v/2026-08-27/']`
       */
      ?: boolean | string[]
      /**
       * Which client files to put in the Workbox precache.
       *
       * Default `false` only precaches the app shell (SvelteKit entry,
       * hashed CSS/fonts, and root icons) so service-worker install/update
       * stays fast on sites with many pages. Per-route nodes and chunks
       * are fetched on demand.
       *
       * - `false`: app shell only
       * - `true`: every matching client file (the previous catch-all glob)
       */
      ?: boolean
    }
    ?: <, 'container' | 'theme'>
    ?:  | string | boolean
    ?: {
      : string
      : string
      ?: string
      /**
       * Darker variant of primary, used for accent text on light backgrounds
       * where the primary color alone lacks contrast.
       * Defaults to `#e11d48` when primary is not customized, otherwise falls back to primary.
       */
      ?: string
      ?: string
      ?: {
        : string
        : string
      }
    }
    ?: {
      ?: []
      ?: 
      ?: 
      ?: boolean | 
      /**
       * Code blocks taller than this many lines start collapsed with an
       * "Expand code" bar. Set to 0 to disable collapsing.
       * @default 30
       */
      ?: number
    }
    ?: {
      ?: string
      ?: {
        ?: string
        ?: string
        ?: string
        ?: string
        ?: string
        ?: string
      }
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      /** Label of the expand bar on collapsed long code blocks */
      ?: string
      ?: {
        ?: string
        ?: string
        ?: string
        ?: string
        ?: string
      }
      ?: string
      /** Label of the language switcher trigger. */
      ?: string
      /** Notice shown after switching locale fell back to that locale's home. */
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      /** Template for page and section badges. Use `{version}` for the version label. */
      ?: string
      /** Compact badge shown beside changed sidebar pages and table-of-contents sections. */
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
    }
    ?: {
      [: string]: string[]
    }
  }
  export type  = <DefaultThemeOptions>

  const : DefaultThemeOptions
  export default 
}

declare module '@sveltepress/theme-default/context' {
  import type {  } from 'svelte/store'

  export interface SveltepressContext {
    : <boolean>
  }
  export const : symbol
}

declare module 'virtual:sveltepress/theme-default/versioning' {
  export * from '@sveltepress/theme-default/dist/components/versioning'
}

declare module 'virtual:sveltepress/theme-default/VersionSelector.svelte' {
  import type {  } from 'svelte'

  const : <{ ?: boolean }>
  export default 
}

declare module 'virtual:sveltepress/theme-default/VersionFallbackNotice.svelte' {
  import type {  } from 'svelte'

  const : 
  export default 
}

declare module 'virtual:sveltepress/theme-default/VersionLifecycleBanner.svelte' {
  import type {  } from 'svelte'

  const : 
  export default 
}
ts
Expand code

navbar

  • title 标题
  • to 链接地址
  • icon 自定义展示 HTML 内容,通常用于展示自定义图标内容
  • external 如果设置为 true,将会展示一个标记外部链接的图标
  • items 子项,如果配置会展示下拉导航

discord

Discord 链接,如果提供将会展示一个 Discord 图标

github

GitHub 仓库链接,如果提供将会展示一个 GitHub 图标

logo

Logo 图片

sidebar

侧边栏可以通过两种方式配置:

自动生成侧边栏

传入一个包含 enabled: true 的对象,即可从路由目录自动生成侧边栏。

  • enabled - 设为 true 启用自动侧边栏生成
  • routesDir - 自定义路由目录路径。默认为 'src/routes'
  • roots - 生成侧边栏的根路径,如 ['/guide/', '/reference/']。未指定时从顶级路由目录自动检测

页面可以通过 frontmatter 控制其在侧边栏中的显示:

  • title - 页面标题,同时用作侧边栏标签
  • sidebarTitle - 覆盖侧边栏标签(优先级高于 title
  • order - 同级排序。数字越小越靠前。默认为 100
  • sidebar - 设为 false 可将此页面从侧边栏中排除
  • collapsible - 侧边栏分组是否可折叠

手动配置侧边栏

传入一个对象,键为分组路由前缀,值为侧边栏项数组:

  • title 组标题
  • collapsible 组是否可折叠
  • to 链接地址
  • items 子链接,若配置该属性,则 to 将会失效,展示一个分组链接

highlighter

一个包含如下属性的代码块高亮相关配置:

  • languages - 自定义支持的语言列表,默认为:['svelte', 'sh', 'js', 'html', 'ts', 'md', 'css', 'scss']
  • themeLight - 日间模式所使用的高亮主题,默认为:vitesse-light
  • themeDark - 夜间模式所使用的高亮主题,默认为:night-owl
  • twoslash - 设置为 true 可以开启 Twoslash 功能. 默认为 false
  • codeCollapseLines - 超过该行数的代码块会默认折叠,默认为 30;设为 0 可关闭折叠。
TIP

你可以在 Shiki Repo 获得所有支持的语言以及主题

editLink

页面底部展示的“在 Github 上编辑此页”链接,例如本站使用:https://github.com/SveltePress/sveltepress/edit/main/packages/docs-site-zh/src/routes/:route

:route 代表路由,例如 src/routes/foo/bar/+page.md => /foo/bar

ga

提供自 Google Analytics ,形如 G-XXXXXXX

配置该项将会自动添加 gtag 相关脚本

语言切换器与默认本地搜索

配置 sveltepress({ locales }) 后,默认主题会在导航栏显示语言切换器(文案可用 i18n.localeSwitcher / i18n.localePageUnavailable)。详见 国际化

未设置 docsearch 或自定义 search 时,主题使用内置本地搜索(Pagefind)。search: false 可完全关闭搜索。详见 搜索

search

受支持的自定义搜索入口,类型为 Component | string,可用于接入 @sveltepress/meilisearch 等 Svelte 搜索组件。字符串用于指定包装组件的源码路径:

import {  } from '@sveltepress/theme-default'

({
  : '/src/lib/MeilisearchSearch.svelte',
})
ts
生产构建

该公开 API 与 M Search 接入均受支持。通过 search 配置的源码 .svelte 路径会被打进静态生产构建——主题在构建期解析该路径并以懒加载 chunk 加载。直接传组件对象不受支持,因为主题选项会以 JSON 序列化到客户端。包装组件用法见 搜索指南

docsearch

  • appId
  • apiKey
  • indexName

阅读 Docsearch 来获得更多信息

仅当未提供 search 时,才会使用 docsearch

pwa

阅读 PWA 章节 来获得更多信息

themeColor

主题色相关

  • light - 日间模式主题色,也会应用在 pwa 顶部窗口导航
  • dark - 夜间模式主题色,也会应用在 pwa 顶部窗口导航
  • gradient - 全站使用到的渐变色,如:首页标题,首页按钮,链接高亮文字
const defaultGradient = {
  start: '#fa709a',
  end: '#fee140',
}
js
  • primary - 站点主色
  • primaryDeep - 浅色背景上用于保证对比度的深主色
  • hover - 鼠标上浮时主色

i18n

一些固定的文本内容,可以被您的配置所覆盖,方便站点国际化

  • onThisPage - "On this page"
  • suggestChangesToThisPage - "Suggest changes to this page"
  • lastUpdateAt - "Last update at:"
  • previousPage - "Previous"
  • nextPage - "Next"
  • expansionTitle - 在 Markdown 以及 Svelte 可折叠代码块上的折叠面板标题:"Click to expand/fold code"
  • expandCode - 长代码块展开栏的文本
  • heroCode - 默认首页代码预览中的本地化文字,包括 titlemessageBeforemessageStrongmessageAftertipLabelcounterLabel
  • versionDeprecated / versionEol - 全局旧版生命周期横条中的提示文本
  • versionDeprecatedLabel / versionEolLabel - 生命周期状态的紧凑标签
  • versionViewCurrent - 打开同一逻辑页面最新版的链接文本
  • versionNewLabel - 页面主标题与段落小节新增徽章的模板文本。使用 {version} 作为版本占位符,默认为 "New in {version}"
  • versionNavigationNewLabel - 侧边栏变化页面,以及自动关联到 :::since 标记的当前页面目录标题旁所显示的紧凑徽章文本,默认为 "New"
  • pwa - PWA 提示弹窗中的文本,下面的每个字段都直接对应到弹窗中对应意义的文本
    • tip
    • reload
    • close
    • appReadyToWorkOffline
    • newContentAvailable
  • footnoteLabel - 自动生成的脚注标题,默认为 "Footnotes"

preBuildIconifyIcons

一些你可能在编写文档过程中用到的 Iconify 图标

为一个对象,键是分类名称,值是该分类下需要预构建的图标集合,下面是此站点的配置

preBuildIconifyIcons: {
  'vscode-icons': ['file-type-svelte', 'file-type-markdown', 'file-type-vite'],
  'logos': ['typescript-icon', 'svelte-kit', 'svelte-icon'],
  'emojione': ['artist-palette'],
  'material-symbols': ['history', 'translate', 'search'],
  'ph': ['smiley', 'layout-duotone'],
  'noto': ['package'],
  'solar': ['chat-square-code-outline', 'reorder-outline'],
  'carbon': ['tree-view-alt', 'import-export'],
  'ic': ['sharp-rocket-launch'],
  'tabler': ['icons'],
  'mdi': ['theme-light-dark'],
  'bi': ['list-nested'],
  'openmoji': ['red-apple'],
}
ts

这些图标看起来像这样:

<script lang="ts">
  import {  } from '@sveltepress/theme-default/components'
  import  from 'virtual:sveltepress/theme-default'
</script>
<div ="flex items-center gap-4 text-[48px] flex-wrap">
  {#each .(. || []) as [, ]}
    {#each  as }
      <div>
        < {} {} />
      </div>
    {/each}
  {/each}
</div>
svelte
View code

全局上下文

全局上下文的键在模块 @sveltepress/theme-default/context 中,你可以通过 getContext API 来获取所有的上下文,下面是一个示例:

isDark: false
<script lang="ts">
  import type { SveltepressContext } from '@sveltepress/theme-default/context'
  import {  } from '@sveltepress/theme-default/context'
  import {  } from 'svelte'

  const {  } = <SveltepressContext>(
</script>

<div class:dark-text={} ="text-10">
  isDark: {}
</div>
<style>
  .dark-text {
    --at-apply: 'text-red';
  }
</style>
svelte
View code

上下文属性一览:

  • $isDark - 用来表示当前的主题是否为暗色,是一个响应式的 svelte store

虚拟模块

virtual:sveltepress/theme-default

这个模块默认导出所有传递给 defaultTheme() 函数的选项

这是当前站点所使用的配置:

{11 entries
    navbar,
    sidebar,
    editLink"https://github.com/SveltePress/sveltepress/edit/main/packages/docs-site/src/routes/:route",
    github"https://github.com/SveltePress/sveltepress",
    logo"/sveltepress.svg",
    discord"https://discord.gg/MeYRrGGxbE",
    ga"G-J2W78BKCHB",
    pwa,
    themeColor,
    preBuildIconifyIcons,
    highlighter
}
<script>
  import {  } from 'svelte-json-discovery'
  import  from 'virtual:sveltepress/theme-default'
</script>

<div ="viewer">
  < ={} />
</div>
<style>
  .viewer {
    max-height: 40vh;
    overflow: auto;
  }
  :global(html.dark) .viewer {
    --discovery-background-color: #1a1a1a;
    --sjd-app-bg: #1a1a1a;
    --sjd-fmt-color: #999;
    --sjd-fmt-hover-color: #aaa;
    --sjd-fmt-property-color: #d17a8c;
    --sjd-fmt-number-color: #0f8dc2;
    --sjd-fmt-atom-color: #0f8dc2;
    --sjd-fmt-string-color: #7faf20;
    --sjd-fmt-string-underline-color: #85ab51;
    --sjd-fmt-string-hover-color: #97cf26;
    --sjd-ui-color: #ccc;
    --sjd-match-bg: #565638;
    --sjd-match-border: #a7a73b;
    --sjd-error-border: #0004;
    --sjd-error-bg: #622b29;
    --sjd-error-color: #c66;
    --sjd-error-message-bg: #443232;
    --sjd-toggle-color: #72b372;
    --sjd-touch-button-color: #aaa;
    --sjd-touch-button-bg: #50505080;
    --sjd-popup-bg: #333;
    --sjd-popup-color: #ccc;
    --sjd-popup-notes-color: #999;
    --sjd-popup-error-color: #e66;
    color-scheme: dark;
  }
</style>
svelte
Expand code
View code

Typescript

您需要在 src/app.d.ts 文件中添加 @sveltepress/theme-default/types 来获得默认主题相关类型提示

/src/app.d.ts
/// <reference types="@sveltepress/theme-default/types" />

// Your other types
ts