Default theme
安装
npm install --save @sveltepress/theme-default 在 vite.config.(js|ts) 中配置
import { } from '@sveltepress/theme-default'
import { } from '@sveltepress/vite'
import { } from 'vite'
const = ({
: [
({/** 配置 */}),
({
: (/** 主题配置 */)
})
],
})
export default 主题配置
类型一览
/// <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
}
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- 同级排序。数字越小越靠前。默认为100sidebar- 设为false可将此页面从侧边栏中排除collapsible- 侧边栏分组是否可折叠
手动配置侧边栏
传入一个对象,键为分组路由前缀,值为侧边栏项数组:
title组标题collapsible组是否可折叠to链接地址items子链接,若配置该属性,则to将会失效,展示一个分组链接
highlighter
一个包含如下属性的代码块高亮相关配置:
languages- 自定义支持的语言列表,默认为:['svelte', 'sh', 'js', 'html', 'ts', 'md', 'css', 'scss']themeLight- 日间模式所使用的高亮主题,默认为:vitesse-lightthemeDark- 夜间模式所使用的高亮主题,默认为:night-owltwoslash- 设置为true可以开启 Twoslash 功能. 默认为falsecodeCollapseLines- 超过该行数的代码块会默认折叠,默认为30;设为0可关闭折叠。
你可以在 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',
}) 该公开 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',
} 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- 默认首页代码预览中的本地化文字,包括title、messageBefore、messageStrong、messageAfter、tipLabel和counterLabelversionDeprecated/versionEol- 全局旧版生命周期横条中的提示文本versionDeprecatedLabel/versionEolLabel- 生命周期状态的紧凑标签versionViewCurrent- 打开同一逻辑页面最新版的链接文本versionNewLabel- 页面主标题与段落小节新增徽章的模板文本。使用{version}作为版本占位符,默认为"New in {version}"versionNavigationNewLabel- 侧边栏变化页面,以及自动关联到:::since标记的当前页面目录标题旁所显示的紧凑徽章文本,默认为"New"pwa- PWA 提示弹窗中的文本,下面的每个字段都直接对应到弹窗中对应意义的文本tipreloadcloseappReadyToWorkOfflinenewContentAvailable
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'],
} 这些图标看起来像这样:
<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> 全局上下文
全局上下文的键在模块 @sveltepress/theme-default/context 中,你可以通过 getContext API 来获取所有的上下文,下面是一个示例:
<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> 上下文属性一览:
$isDark- 用来表示当前的主题是否为暗色,是一个响应式的 svelte store
虚拟模块
virtual:sveltepress/theme-default
这个模块默认导出所有传递给 defaultTheme() 函数的选项
这是当前站点所使用的配置:
<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> Typescript
您需要在 src/app.d.ts 文件中添加 @sveltepress/theme-default/types 来获得默认主题相关类型提示
/// <reference types="@sveltepress/theme-default/types" />
// Your other types