插件选项

}
export interface ResolvedTheme {
  ResolvedTheme.name: stringname: string
  ResolvedTheme.globalLayout: stringglobalLayout: string
  ResolvedTheme.pageLayout: stringpageLayout: string
  ResolvedTheme.vitePlugins: ThemeVitePluginsvitePlugins: type ThemeVitePlugins = /*unresolved*/ anyThemeVitePlugins
  ResolvedTheme.highlighter: Highlighterhighlighter: type Highlighter = /*unresolved*/ anyHighlighter
ts

siteConfig

* On the newer SvelteKit project layout there is no `svelte.config.js` and all
* config (`compilerOptions`, `adapter`, ...) is passed inline to `sveltekit()`
* in `vite.config.ts`. Forward those options through `sveltepress()` so the
* standalone `sveltekit()` plugin can be removed (having both crashes the dev
ts
  • title: 站点标题,默认为:'Untitled site'
  • description: 站点描述,默认为:'Build by sveltepress'

addInspect

如果设置为 true,将会添加 Vite plugin inspect

theme

查看下方 ResolvedTheme

remarkPlugins

阅读 Remark plugins 来获得更多信息

rehypePlugins

阅读 Rehype plugins 来获得更多信息

自定义 remark 与 rehype 插件顺序

remarkPluginsrehypePlugins 可以是以下两种形式:

  1. 一个 Plugins 数组. 这里提供的插件将会自动在主题提供的插件之后运行
  2. 一个函数,接受 themeRemarkPlugins 作为参数,然后返回一个 Plugins 数组,例如:
vite.config.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'
export default 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[] | undefined

Array of vite plugins to use.

plugins
: [
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({ SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme(/* 主题选项 */), SveltepressVitePluginOptions.remarkPlugins?: Plugin[] | RemarkPluginsOrderer | undefinedremarkPlugins: (themeRemarkPlugins: Plugin[]themeRemarkPlugins) => { // 添加你的自定义插件,并且可以控制最终的调用顺序 return [ ...themeRemarkPlugins: Plugin[]themeRemarkPlugins ] } }) ] })
ts

llms

在生产构建时生成便于机器读取的文档索引。默认关闭。

vite.config.ts
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'

function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
  SveltepressVitePluginOptions.siteConfig?: SiteConfig | undefinedsiteConfig: {
    SiteConfig.title?: string | undefinedtitle: 'My docs',
    SiteConfig.description?: string | undefineddescription: 'Documentation for my project',
  },
  SveltepressVitePluginOptions.llms?: LlmsConfig | undefinedllms: {
    LlmsConfig.enabled?: boolean | undefinedenabled: true,
    LlmsConfig.baseUrl?: string | undefinedbaseUrl: 'https://docs.example.com',
    LlmsConfig.filter?: ((filePath: string, frontmatter: Record<string, unknown>) => boolean) | undefinedfilter: (_filePath: string_filePath, frontmatter: Record<string, unknown>frontmatter) => frontmatter: Record<string, unknown>frontmatter.unknownllms !== false,
  },
})
ts
选项类型默认值作用
enabledbooleanfalse构建时写入 llms.txtllms-full.txt
titlestringsiteConfig.title两个生成文件使用的标题。
descriptionstringsiteConfig.description两个生成文件使用的描述。
baseUrlstring''拼接在路由链接前的站点绝对地址。
routesDirstring'src/routes'扫描页面的目录。
filter(filePath, frontmatter) => boolean排除指定页面。
sort(a, b) => number路由路径自定义页面顺序。

生成器只读取 Markdown 页面,不包含纯 Svelte 页面和运行时数据。启用增量文档版本后,历史索引读取每个页面冻结的 Markdown 构件,而不是当前源码。构建会同时把文件写入 static/ 和生产 bundle,确保干净 CI 构建的部署产物也包含这些文件。请明确选择提交 static/ 副本,或忽略并在 CI 中统一重新生成。

版本变更发现

versions

文档版本管理默认通过 sveltepress.versions.json 自动发现。也可以关闭发现,或显式指定其他清单路径:

import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'

function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
  
SveltepressVitePluginOptions.versions?: false | {
    manifest?: string;
} | undefined

Enable document version management by discovering sveltepress.versions.json, override its location, or disable discovery.

versions
: false,
}) function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
SveltepressVitePluginOptions.versions?: false | {
    manifest?: string;
} | undefined

Enable document version management by discovering sveltepress.versions.json, override its location, or disable discovery.

versions
: { manifest?: string | undefinedmanifest: 'config/document-versions.json' },
})
ts

启用后,virtual:sveltepress/versions 会在清单与路由辅助函数之外,额外导出 changeSetsresolveVersionChanges(versionId?)。快照与变化总览用法请参阅文档版本管理

多语言、Pagefind 与 locale hooks

locales

按需启用的多语言配置,键为 URL 前缀('/''/zh/' 等)。每个条目提供 langlabel 以及该语言的主题选项。省略时站点保持单语言。详见国际化

pagefind

控制生产构建后的 Pagefind 索引(本地搜索)。默认启用;设为 pagefind: false 可关闭,或传入 PagefindOptions。启用文档版本时,历史索引由 syncHistoricalPagefind 冻结。

virtual:sveltepress/locale

配置 locales 后,该虚拟模块导出 localesresolveLocaleresolveLocalizedPathresolveLocaleSwitch。未配置时 localesnull

createLocaleHandle

/vite/hooks 导入,在 SSR 阶段按当前语言设置 <html lang>。用法见国际化指南

ResolvedTheme

* server with duplicated Svelte compilation).
*/
export type type SvelteKitOptions = anySvelteKitOptions = type Parameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? P : never

Obtain the parameters of a function type in a tuple

Parameters
<typeof sveltekit>[0]
export type type RemarkLiveCode = anyRemarkLiveCode = Plugin<[], any> export type type Highlighter = (code: string, lang: BundledLanguage, meta?: string) => string | Promise<string>Highlighter = (code: stringcode: string, lang: BundledLanguagelang: type BundledLanguage = /*unresolved*/ anyBundledLanguage, meta: string | undefinedmeta?: string) => string | interface Promise<T>

Represents the completion of an asynchronous operation

Promise
<string>
export type type ThemeVitePlugins = PluginOption[] | ((corePlugin: PluginOption) => Promise<PluginOption[]>) | ((corePlugin: PluginOption) => PluginOption[])ThemeVitePlugins = type PluginOption = /*unresolved*/ anyPluginOption[] | ((corePlugin: PluginOptioncorePlugin: type PluginOption = /*unresolved*/ anyPluginOption) => interface Promise<T>

Represents the completion of an asynchronous operation

Promise
<type PluginOption = /*unresolved*/ anyPluginOption[]>) | ((corePlugin: PluginOptioncorePlugin: type PluginOption = /*unresolved*/ anyPluginOption) => type PluginOption = /*unresolved*/ anyPluginOption[])
export interface SiteConfig { SiteConfig.title?: string | undefinedtitle?: string SiteConfig.description?: string | undefineddescription?: string
ts

name

主题名称

globalLayout

全局布局文件的绝对路径, 应当为一个 svelte 文件 例如:path.resolve(process.cwd(), 'ThemeGlobalLayout.svelte')

pageLayout

页面布局文件的绝对路径, 应当为一个 svelte 文件 例如:path.resolve(process.cwd(), 'ThemePageLayout.svelte')

vitePlugins

  • 如果传递了一个单一插件或者一组插件,这些插件将会在 sveltepress 核心插件之前被注册
  • 如果传递了一个函数,将会接受 sveltepress 插件作为入参,并且该函数需要返回插件组,您可以通过此方式来自定义插件顺序
关于提供 Vite 插件选项

也许这种行为显得比较奇怪,但是当主题需要添加一些自定义虚拟模块时会很有用

highlighter

代码高亮渲染函数 例如,默认主题使用了 shiki. 阅读 默认主题高亮器源码 查看具体用法。

remarkPlugins

阅读 Remark plugins 来获得更多信息

rehypePlugins

阅读 Rehype plugins 来获得更多信息

插件顺序

主题提供的 remark 以及 rehype 插件将会在 vite 插件提供的之前调用 例如:

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'
export default 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[] | undefined

Array of vite plugins to use.

plugins
: [
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({ SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme(/* 默认主题选项 */), SveltepressVitePluginOptions.remarkPlugins?: Plugin[] | RemarkPluginsOrderer | undefinedremarkPlugins: [/* 你的 remark 插件 */] }) ] })
ts

“你的 remark 插件”将会在默认主题中的 remark plugins 之后调用

footnoteLabel

自定义脚注标题,默认为:"Footnotes"

虚拟模块

virtual:sveltepress/site

这个模块默认导出 siteConfig,示例:

<script>
  import 
const siteConfig: {
    title: string;
    description: string;
}
siteConfig
from 'virtual:sveltepress/site'
</script> <p>站点标题为:{
const siteConfig: {
    title: string;
    description: string;
}
siteConfig
.title: stringtitle}</p>
<p>站点描述:{
const siteConfig: {
    title: string;
    description: string;
}
siteConfig
.description: stringdescription}</p>
svelte

更低层级的 markdown API

@sveltepress/vite 包导出了一个名为 mdToSvelte 的更低层级的函数,它支撑了所有 Sveltepress 的 markdown 渲染

这个函数可以作为一些 Markdown 转换 Svelte 工具的基础,这是一个使用的示例

import { 
function mdToSvelte({ mdContent, remarkPlugins, rehypePlugins, highlighter, filename, footnoteLabel, data: inputData, }: CompileOptions): Promise<{
    data: Record<string, any>;
    code: string;
}>
mdToSvelte
} from '@sveltepress/vite'
const const mdSource: "\ ---\ title: Foo\ ---\ <script>\ const foo = 'bar'\ </script>\ # Title\ \ foo in script is: {foo}\ \ [Foo Link](https://foo.bar)\ "mdSource = ` --- title: Foo --- <script> const foo = 'bar' </script> # Title foo in script is: {foo} [Foo Link](https://foo.bar) ` const { const code: stringcode, const data: Record<string, any>data } = await
function mdToSvelte({ mdContent, remarkPlugins, rehypePlugins, highlighter, filename, footnoteLabel, data: inputData, }: CompileOptions): Promise<{
    data: Record<string, any>;
    code: string;
}>
mdToSvelte
({
CompileOptions.mdContent: stringmdContent: const mdSource: "\ ---\ title: Foo\ ---\ <script>\ const foo = 'bar'\ </script>\ # Title\ \ foo in script is: {foo}\ \ [Foo Link](https://foo.bar)\ "mdSource, CompileOptions.remarkPlugins?: (Plugin<any[], any> | [Plugin<any[], any>, any])[] | undefinedremarkPlugins: [], // 自定义 remark 插件 CompileOptions.rehypePlugins?: Plugin[] | undefinedrehypePlugins: [], // 自定义 rehype 插件 CompileOptions.highlighter?: Highlighter | undefinedhighlighter: async (code: stringcode, lang: BundledLanguagelang, meta: string | undefinedmeta) => var Promise: PromiseConstructor

Represents the completion of an asynchronous operation

Promise
.PromiseConstructor.resolve<string>(value: string): Promise<string> (+2 overloads)

Creates a new resolved promise for the provided value.

@paramvalue A promise.@returnsA promise whose internal state matches the provided promise.
resolve
('高亮后的 HTML 结果'), // 自定义代码高亮函数
CompileOptions.filename: stringfilename: 'Foo.svelte', // 虚拟文件路径 }) // 渲染后的 Svelte 代码 const code: stringcode // 解析后的 frontmatter 对象,这里是: { title: 'Foo' } const data: Record<string, any>data
ts
按字面量准备代码块

@sveltepress/vite/highlight

@sveltepress/vite/highlight 导入 prepareCodeBlock,并在不应转换源码时将 { mode: 'literal' } 作为第三个参数传入。// [svp! hl] 等代码指令和首行的 // @noErrors 会原样保留在 processedCode 中,同时元数据解析仍会处理 titleln

import { function prepareCodeBlock(code: string, meta?: string, options?: PrepareCodeBlockOptions): PreparedCodeBlock

Parse code block metadata and process code commands. Call BEFORE Shiki highlighting.

prepareCodeBlock
} from '@sveltepress/vite/highlight'
const const prepared: PreparedCodeBlockprepared = function prepareCodeBlock(code: string, meta?: string, options?: PrepareCodeBlockOptions): PreparedCodeBlock

Parse code block metadata and process code commands. Call BEFORE Shiki highlighting.

prepareCodeBlock
(
'// @noErrors\ const value = 1 ', 'title="source.md" ln', { PrepareCodeBlockOptions.mode?: "commands" | "literal" | undefined

Use literal mode to skip code commands and

@noErrorsprocessing.
mode
: 'literal' },
)
ts

这里 prepared.processedCode 与输入完全相同,prepared.title'source.md'prepared.containLineNumberstrueprepared.noErrors 保持为 false,因为字面量模式会保留 @noErrors,而不会把它作为指令处理。

Typescript

您需要在 src/app.d.ts 文件中包含 @sveltepress/vite/types 来获得相关的类型提示

/src/app.d.ts
/// <reference types="@sveltepress/vite/types" />

// Your other types
ts