插件选项
}
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 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 title: 站点标题,默认为:'Untitled site'description: 站点描述,默认为:'Build by sveltepress'
addInspect
如果设置为 true,将会添加 Vite plugin inspect
theme
查看下方 ResolvedTheme
remarkPlugins
阅读 Remark plugins 来获得更多信息
rehypePlugins
阅读 Rehype plugins 来获得更多信息
remarkPlugins 与 rehypePlugins 可以是以下两种形式:
- 一个
Plugins数组. 这里提供的插件将会自动在主题提供的插件之后运行 - 一个函数,接受
themeRemarkPlugins作为参数,然后返回一个Plugins数组,例如:
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[] | undefinedArray 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
]
}
})
]
}) llms
在生产构建时生成便于机器读取的文档索引。默认关闭。
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,
},
}) | 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
enabled | boolean | false | 构建时写入 llms.txt 和 llms-full.txt。 |
title | string | siteConfig.title | 两个生成文件使用的标题。 |
description | string | siteConfig.description | 两个生成文件使用的描述。 |
baseUrl | string | '' | 拼接在路由链接前的站点绝对地址。 |
routesDir | string | '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' },
}) 启用后,virtual:sveltepress/versions 会在清单与路由辅助函数之外,额外导出 changeSets 和 resolveVersionChanges(versionId?)。快照与变化总览用法请参阅文档版本管理。
locales
按需启用的多语言配置,键为 URL 前缀('/'、'/zh/' 等)。每个条目提供 lang、label 以及该语言的主题选项。省略时站点保持单语言。详见国际化。
pagefind
控制生产构建后的 Pagefind 索引(本地搜索)。默认启用;设为 pagefind: false 可关闭,或传入 PagefindOptions。启用文档版本时,历史索引由 syncHistoricalPagefind 冻结。
virtual:sveltepress/locale
配置 locales 后,该虚拟模块导出 locales、resolveLocale、resolveLocalizedPath、resolveLocaleSwitch。未配置时 locales 为 null。
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 : neverObtain 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 name
主题名称
globalLayout
全局布局文件的绝对路径, 应当为一个 svelte 文件 例如:path.resolve(process.cwd(), 'ThemeGlobalLayout.svelte')
pageLayout
页面布局文件的绝对路径, 应当为一个 svelte 文件 例如:path.resolve(process.cwd(), 'ThemePageLayout.svelte')
vitePlugins
- 如果传递了一个单一插件或者一组插件,这些插件将会在
sveltepress核心插件之前被注册 - 如果传递了一个函数,将会接受
sveltepress插件作为入参,并且该函数需要返回插件组,您可以通过此方式来自定义插件顺序
也许这种行为显得比较奇怪,但是当主题需要添加一些自定义虚拟模块时会很有用
highlighter
代码高亮渲染函数 例如,默认主题使用了 shiki. 阅读 默认主题高亮器源码 查看具体用法。
remarkPlugins
阅读 Remark plugins 来获得更多信息
rehypePlugins
阅读 Rehype plugins 来获得更多信息
主题提供的 remark 以及 rehype 插件将会在 vite 插件提供的之前调用 例如:
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[] | undefinedArray 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 插件 */]
})
]
}) “你的 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> 更低层级的 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: PromiseConstructorRepresents 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.
resolve('高亮后的 HTML 结果'), // 自定义代码高亮函数
CompileOptions.filename: stringfilename: 'Foo.svelte', // 虚拟文件路径
})
// 渲染后的 Svelte 代码
const code: stringcode
// 解析后的 frontmatter 对象,这里是: { title: 'Foo' }
const data: Record<string, any>data @sveltepress/vite/highlight
从 @sveltepress/vite/highlight 导入 prepareCodeBlock,并在不应转换源码时将 { mode: 'literal' } 作为第三个参数传入。// [svp! hl] 等代码指令和首行的 // @noErrors 会原样保留在 processedCode 中,同时元数据解析仍会处理 title 和 ln。
import { function prepareCodeBlock(code: string, meta?: string, options?: PrepareCodeBlockOptions): PreparedCodeBlockParse 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): PreparedCodeBlockParse code block metadata and process code commands.
Call BEFORE Shiki highlighting.
prepareCodeBlock(
'// @noErrors\
const value = 1 ',
'title="source.md" ln',
{ PrepareCodeBlockOptions.mode?: "commands" | "literal" | undefinedUse literal mode to skip code commands and
mode: 'literal' },
) 这里 prepared.processedCode 与输入完全相同,prepared.title 为 'source.md',prepared.containLineNumbers 为 true。prepared.noErrors 保持为 false,因为字面量模式会保留 @noErrors,而不会把它作为指令处理。
Typescript
您需要在 src/app.d.ts 文件中包含 @sveltepress/vite/types 来获得相关的类型提示
/// <reference types="@sveltepress/vite/types" />
// Your other types