安装
npm install --save @sveltepress/theme-default yarn add @sveltepress/theme-default pnpm install @sveltepress/theme-default bun add @sveltepress/theme-default 在 vite.config.(js|ts) 中配置
import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.
defineConfig } from 'vite'
const const config: UserConfigconfig = function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.
defineConfig({
UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
plugins: [
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({/** 配置 */}),
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme(/** 主题配置 */)
})
],
})
export default const config: UserConfigconfig 主题配置
类型一览
/// <reference types="vite/client" />
/// <reference types="@sveltepress/vite/types" />
/// <reference types="@sveltejs/kit/vite" />
declare module 'virtual:sveltepress/theme-default' {
import type { import DocSearchPropsDocSearchProps } from '@sveltepress/docsearch/types'
import type { import CreateTwoslashSvelteOptionsCreateTwoslashSvelteOptions } from '@sveltepress/twoslash'
import type { import LoadThemeLoadTheme } from '@sveltepress/vite'
import type { import SvelteKitPWAOptionsSvelteKitPWAOptions } from '@vite-pwa/sveltekit'
import type { import BundledThemeBundledTheme } from 'shiki'
import type { import BundledLanguageBundledLanguage } from 'shiki/langs'
import type { interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component } from 'svelte'
export interface WithTitle {
WithTitle.title?: string | undefinedtitle?: string
}
export interface LinkItem extends WithTitle {
LinkItem.icon?: string | undefinedicon?: string
LinkItem.to?: string | undefinedto?: string
LinkItem.external?: boolean | undefinedexternal?: boolean
LinkItem.collapsible?: boolean | undefinedcollapsible?: boolean
LinkItem.items?: LinkItem[] | undefineditems?: LinkItem[]
}
export interface AutoSidebarOptions {
/**
* Enable auto-generated sidebar
*/
AutoSidebarOptions.enabled: booleanEnable auto-generated sidebar
enabled: boolean
/**
* Routes directory, default 'src/routes'
*/
AutoSidebarOptions.routesDir?: string | undefinedRoutes directory, default 'src/routes'
routesDir?: string
/**
* Root paths to generate sidebar for, e.g. ['/guide/', '/reference/']
* If not specified, auto-detect from top-level route directories
*/
AutoSidebarOptions.roots?: string[] | undefinedRoot paths to generate sidebar for, e.g. ['/guide/', '/reference/']
If not specified, auto-detect from top-level route directories
roots?: string[]
}
export interface DefaultThemeOptions {
DefaultThemeOptions.navbar?: LinkItem[] | undefinednavbar?: interface Array<T>Array<LinkItem>
DefaultThemeOptions.github?: string | undefinedgithub?: string
DefaultThemeOptions.logo?: string | undefinedlogo?: string
DefaultThemeOptions.sidebar?: AutoSidebarOptions | Record<string, LinkItem[]> | undefinedsidebar?: type Record<K extends keyof any, T> = { [P in K]: T; }Construct a type with a set of properties K of type T
Record<string, LinkItem[]> | AutoSidebarOptions
DefaultThemeOptions.editLink?: string | undefinededitLink?: string
DefaultThemeOptions.discord?: string | undefineddiscord?: string
DefaultThemeOptions.ga?: string | undefinedga?: string
DefaultThemeOptions.pwa?: (SvelteKitPWAOptions & {
darkManifest?: string;
precachePages?: boolean | string[];
precacheClient?: boolean;
}) | undefined
pwa?: import SvelteKitPWAOptionsSvelteKitPWAOptions & {
darkManifest?: string | undefineddarkManifest?: 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/']`
*/
precachePages?: boolean | string[] | undefinedWhich 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/']
precachePages?: 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)
*/
precacheClient?: boolean | undefinedWhich 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)
precacheClient?: boolean
}
DefaultThemeOptions.docsearch?: Omit<DocSearchProps, "theme" | "container"> | undefineddocsearch?: type Omit<T, K extends keyof any> = { [P in Exclude<keyof T, K>]: T[P]; }Construct a type with the properties of T except for those in type K.
Omit<import DocSearchPropsDocSearchProps, 'container' | 'theme'>
DefaultThemeOptions.search?: string | boolean | Component<{}, {}, string> | undefinedsearch?: interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component | string | boolean
DefaultThemeOptions.themeColor?: {
light: string;
dark: string;
primary?: string;
primaryDeep?: string;
hover?: string;
gradient?: {
start: string;
end: string;
};
} | undefined
themeColor?: {
light: stringlight: string
dark: stringdark: string
primary?: string | undefinedprimary?: 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.
*/
primaryDeep?: string | undefinedDarker 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.
primaryDeep?: string
hover?: string | undefinedhover?: string
gradient?: {
start: string;
end: string;
} | undefined
gradient?: {
start: stringstart: string
end: stringend: string
}
}
DefaultThemeOptions.highlighter?: {
languages?: BundledLanguage[];
themeLight?: BundledTheme;
themeDark?: BundledTheme;
twoslash?: boolean | CreateTwoslashSvelteOptions;
codeCollapseLines?: number;
} | undefined
highlighter?: {
languages?: BundledLanguage[] | undefinedlanguages?: import BundledLanguageBundledLanguage[]
themeLight?: anythemeLight?: import BundledThemeBundledTheme
themeDark?: anythemeDark?: import BundledThemeBundledTheme
twoslash?: anytwoslash?: boolean | import CreateTwoslashSvelteOptionsCreateTwoslashSvelteOptions
/**
* Code blocks taller than this many lines start collapsed with an
* "Expand code" bar. Set to 0 to disable collapsing.
* @default 30
*/
codeCollapseLines?: number | undefinedCode blocks taller than this many lines start collapsed with an
"Expand code" bar. Set to 0 to disable collapsing.
codeCollapseLines?: number
}
DefaultThemeOptions.i18n?: {
navbarMenu?: string;
heroCode?: {
title?: string;
messageBefore?: string;
messageStrong?: string;
messageAfter?: string;
tipLabel?: string;
counterLabel?: string;
};
onThisPage?: string;
suggestChangesToThisPage?: string;
lastUpdateAt?: string;
previousPage?: string;
nextPage?: string;
expansionTitle?: string;
expandCode?: string;
pwa?: {
tip?: string;
reload?: string;
close?: string;
appReadyToWorkOffline?: string;
newContentAvailable?: string;
};
... 22 more ...;
searchClear?: string;
} | undefined
i18n?: {
navbarMenu?: string | undefinednavbarMenu?: string
heroCode?: {
title?: string;
messageBefore?: string;
messageStrong?: string;
messageAfter?: string;
tipLabel?: string;
counterLabel?: string;
} | undefined
heroCode?: {
title?: string | undefinedtitle?: string
messageBefore?: string | undefinedmessageBefore?: string
messageStrong?: string | undefinedmessageStrong?: string
messageAfter?: string | undefinedmessageAfter?: string
tipLabel?: string | undefinedtipLabel?: string
counterLabel?: string | undefinedcounterLabel?: string
}
onThisPage?: string | undefinedonThisPage?: string
suggestChangesToThisPage?: string | undefinedsuggestChangesToThisPage?: string
lastUpdateAt?: string | undefinedlastUpdateAt?: string
previousPage?: string | undefinedpreviousPage?: string
nextPage?: string | undefinednextPage?: string
expansionTitle?: string | undefinedexpansionTitle?: string
/** Label of the expand bar on collapsed long code blocks */
expandCode?: string | undefinedLabel of the expand bar on collapsed long code blocks
expandCode?: string
pwa?: {
tip?: string;
reload?: string;
close?: string;
appReadyToWorkOffline?: string;
newContentAvailable?: string;
} | undefined
pwa?: {
tip?: string | undefinedtip?: string
reload?: string | undefinedreload?: string
close?: string | undefinedclose?: string
appReadyToWorkOffline?: string | undefinedappReadyToWorkOffline?: string
newContentAvailable?: string | undefinednewContentAvailable?: string
}
footnoteLabel?: string | undefinedfootnoteLabel?: string
/** Label of the language switcher trigger. */
localeSwitcher?: string | undefinedLabel of the language switcher trigger.
localeSwitcher?: string
/** Notice shown after switching locale fell back to that locale's home. */
localePageUnavailable?: string | undefinedNotice shown after switching locale fell back to that locale's home.
localePageUnavailable?: string
versionSelector?: string | undefinedversionSelector?: string
versionPageUnavailable?: string | undefinedversionPageUnavailable?: string
versionDeprecated?: string | undefinedversionDeprecated?: string
versionEol?: string | undefinedversionEol?: string
versionViewCurrent?: string | undefinedversionViewCurrent?: string
versionDeprecatedLabel?: string | undefinedversionDeprecatedLabel?: string
versionEolLabel?: string | undefinedversionEolLabel?: string
versionSearchUnavailable?: string | undefinedversionSearchUnavailable?: string
/** Template for page and section badges. Use `{version}` for the version label. */
versionNewLabel?: string | undefinedTemplate for page and section badges. Use {version} for the version label.
versionNewLabel?: string
/** Compact badge shown beside changed sidebar pages and table-of-contents sections. */
versionNavigationNewLabel?: string | undefinedCompact badge shown beside changed sidebar pages and table-of-contents sections.
versionNavigationNewLabel?: string
versionChangesSelector?: string | undefinedversionChangesSelector?: string
versionChangesNewPages?: string | undefinedversionChangesNewPages?: string
versionChangesUpdatedPages?: string | undefinedversionChangesUpdatedPages?: string
versionChangesNoBaseline?: string | undefinedversionChangesNoBaseline?: string
versionChangesEmpty?: string | undefinedversionChangesEmpty?: string
searchPlaceholder?: string | undefinedsearchPlaceholder?: string
searchNoResults?: string | undefinedsearchNoResults?: string
searchDevNotice?: string | undefinedsearchDevNotice?: string
searchClose?: string | undefinedsearchClose?: string
searchClear?: string | undefinedsearchClear?: string
}
DefaultThemeOptions.preBuildIconifyIcons?: {
[iconSetName: string]: string[];
} | undefined
preBuildIconifyIcons?: {
[iconSetName: stringiconSetName: string]: string[]
}
}
export type type ThemeDefault = LoadTheme<DefaultThemeOptions>ThemeDefault = import LoadThemeLoadTheme<DefaultThemeOptions>
const const options: DefaultThemeOptionsoptions: DefaultThemeOptions
export default const options: DefaultThemeOptionsoptions
}
declare module '@sveltepress/theme-default/context' {
import type { interface Writable<T>Writable interface for both updating and subscribing.
Writable } from 'svelte/store'
export interface SveltepressContext {
SveltepressContext.isDark: Writable<boolean>isDark: interface Writable<T>Writable interface for both updating and subscribing.
Writable<boolean>
}
export const const SVELTEPRESS_CONTEXT_KEY: symbolSVELTEPRESS_CONTEXT_KEY: symbol
export const const TITLE_ROW_ACTION_KEY: symbolTITLE_ROW_ACTION_KEY: symbol
export interface TitleRowAction {
TitleRowAction.href: stringhref: string
TitleRowAction.label: stringlabel: string
}
export interface TitleRowActionContext {
readonly TitleRowActionContext.current: TitleRowAction | undefinedcurrent: TitleRowAction | undefined
}
}
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 { interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component } from 'svelte'
const
const component: Component<{
mobile?: boolean;
}, {}, string>
component: interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component<{ mobile?: boolean | undefinedmobile?: boolean }>
export default
const component: Component<{
mobile?: boolean;
}, {}, string>
component
}
declare module 'virtual:sveltepress/theme-default/VersionFallbackNotice.svelte' {
import type { interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component } from 'svelte'
const const component: Component<{}, {}, string>component: interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component
export default const component: Component<{}, {}, string>component
}
declare module 'virtual:sveltepress/theme-default/VersionLifecycleBanner.svelte' {
import type { interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component } from 'svelte'
const const component: Component<{}, {}, string>component: interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>Can be used to create strongly typed Svelte components.
Example:
You have component library on npm called component-library, from which
you export a component called MyComponent. For Svelte+TypeScript users,
you want to provide typings. Therefore you create a index.d.ts:
import type { Component } from 'svelte';
export declare const MyComponent: Component<{ foo: string }> {}
Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:
<script lang="ts">
import { MyComponent } from "component-library";
</script>
<MyComponent foo={'bar'} />
Component
export default const component: Component<{}, {}, string>component
}
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/']。未指定时从顶级路由目录自动检测。历史版本快照目录(/v/{id}/,包括按语言组合的路径)会被跳过。
页面可以通过 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 { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'
function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
DefaultThemeOptions.search?: string | boolean | Component<{}, {}, string> | undefinedsearch: '/src/lib/MeilisearchSearch.svelte',
}) 该公开 API 与 M Search 接入均受支持。通过 search 配置的源码 .svelte 路径会被打进静态生产构建——主题在构建期解析该路径并以懒加载 chunk 加载。直接传组件对象不受支持,因为主题选项会以 JSON 序列化到客户端。包装组件用法见搜索指南。
docsearch
- appId
- apiKey
- indexName
阅读 Docsearch 来获得更多信息
仅当未提供
search时,才会使用docsearch。
pwa
阅读 PWA 章节 来获得更多信息
pwa.precacheClient(默认 false)只预缓存应用壳。设为 true 可恢复之前的全量客户端 glob。HTML 策略仍由 pwa.precachePages 控制。
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"
标题行操作
默认主题的 PageLayout 可以在 h1 行上、标题以及版本新增徽章之后渲染一个可选控件。不传入时保持现有标题行。
向 PageLayout 传入 titleAction snippet,或通过 @sveltepress/theme-default/context 的 TITLE_ROW_ACTION_KEY 提供 { current } 对象(current 为 { href, label } 或 undefined):
<script>
import { const TITLE_ROW_ACTION_KEY: symbolTITLE_ROW_ACTION_KEY } from '@sveltepress/theme-default/context'
import { function setContext<T>(key: any, context: T): TAssociates an arbitrary context object with the current component and the specified key
and returns that object. The context is then available to the component itself and all of its
descendants (including slotted content) with getContext.
Like lifecycle functions, this must be called during component initialisation.
createContext is a type-safe alternative.
setContext } from 'svelte'
const
const action: {
href: string;
label: string;
}
action =
function $derived<{
href: string;
label: string;
}>(expression: {
href: string;
label: string;
}): {
href: string;
label: string;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
$
function $derived<{
href: string;
label: string;
}>(expression: {
href: string;
label: string;
}): {
href: string;
label: string;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
derived({
href: stringhref: '/playground/markdown/basic-writing/',
label: stringlabel: '在演练场中打开',
})
setContext<{
readonly current: {
href: string;
label: string;
};
}>(key: any, context: {
readonly current: {
href: string;
label: string;
};
}): {
readonly current: {
href: string;
label: string;
};
}
Associates an arbitrary context object with the current component and the specified key
and returns that object. The context is then available to the component itself and all of its
descendants (including slotted content) with getContext.
Like lifecycle functions, this must be called during component initialisation.
createContext is a type-safe alternative.
setContext(const TITLE_ROW_ACTION_KEY: symbolTITLE_ROW_ACTION_KEY, {
get
current: {
href: string;
label: string;
}
current() {
return
const action: {
href: string;
label: string;
}
action
},
})
</script> 该操作是同页链接。主题消费者不会自动获得 SveltePress 文档站专用的控件,除非自行设置。
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 {
type IconifyIcon = SvelteComponent<Record<string, any>, any, any>
const IconifyIcon: LegacyComponentType
IconifyIcon } from '@sveltepress/theme-default/components'
import const themeOptions: DefaultThemeOptionsthemeOptions from 'virtual:sveltepress/theme-default'
</script>
<div class: stringclass="flex items-center gap-4 text-[48px] flex-wrap">
{#each var Object: ObjectConstructorProvides functionality common to all JavaScript objects.
Object.
ObjectConstructor.entries<string[]>(o: {
[s: string]: string[];
} | ArrayLike<string[]>): [string, string[]][] (+1 overload)
Returns an array of key/values of the enumerable own properties of an object
entries(const themeOptions: DefaultThemeOptionsthemeOptions.
DefaultThemeOptions.preBuildIconifyIcons?: {
[iconSetName: string]: string[];
} | undefined
preBuildIconifyIcons || []) as [let collection: stringcollection, let names: string[]names]}
{#each let names: string[]names as let name: stringname}
<div>
<const IconifyIcon: LegacyComponentTypeIconifyIcon {collection: stringcollection} {name: stringname} />
</div>
{/each}
{/each}
</div> 全局上下文
全局上下文的键在模块 @sveltepress/theme-default/context 中,你可以通过 getContext API 来获取所有的上下文,下面是一个示例:
<script lang="ts">
import type { SveltepressContext } from '@sveltepress/theme-default/context'
import { const SVELTEPRESS_CONTEXT_KEY: symbolSVELTEPRESS_CONTEXT_KEY } from '@sveltepress/theme-default/context'
import { function getContext<T>(key: any): TRetrieves the context set with the specified key in the current component or any of its
ancestors. If multiple components set the same key, the value from the closest one is returned.
A setContext call in the current component is only visible to getContext calls that run after it.
Must be called during component initialisation.
createContext is a type-safe alternative.
getContext } from 'svelte'
const { const isDark: Writable<boolean>isDark } = getContext<SveltepressContext>(key: any): SveltepressContextRetrieves the context set with the specified key in the current component or any of its
ancestors. If multiple components set the same key, the value from the closest one is returned.
A setContext call in the current component is only visible to getContext calls that run after it.
Must be called during component initialisation.
createContext is a type-safe alternative.
getContext<SveltepressContext>(const SVELTEPRESS_CONTEXT_KEY: symbolSVELTEPRESS_CONTEXT_KEYlet $isDark: boolean)
</script>
<div class:dark-text={let $isDark: boolean$let $isDark: booleanisDark} class: stringclass="text-10">
isDark: {let $isDark: boolean$let $isDark: booleanisDark}
</div>
<style>
.dark-text {
--at-apply: 'text-red';
}
</style> 上下文属性一览:
$isDark- 用来表示当前的主题是否为暗色,是一个响应式的 svelte store
虚拟模块
virtual:sveltepress/theme-default
这个模块默认导出所有传递给 defaultTheme() 函数的选项
这是当前站点所使用的配置:
<script>
import {
type JsonViewer = SvelteComponent<Record<string, any>, any, any>
const JsonViewer: LegacyComponentType
JsonViewer } from 'svelte-json-discovery'
import const themeOptions: DefaultThemeOptionsthemeOptions from 'virtual:sveltepress/theme-default'
</script>
<div class: stringclass="viewer">
<const JsonViewer: LegacyComponentTypeJsonViewer data: DefaultThemeOptionsdata={const themeOptions: DefaultThemeOptionsthemeOptions} />
</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