Vite 插件

插件选项

}
export interface ResolvedTheme {
  : string
  : string
  : string
  : 
  :

`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 来获得更多信息

自定义 remark 与 rehype 插件顺序

remarkPlugins 与 rehypePlugins 可以是以下两种形式：

一个 Plugins 数组. 这里提供的插件将会自动在主题提供的插件之后运行
一个函数，接受 themeRemarkPlugins 作为参数，然后返回一个 Plugins 数组，例如：

vite.config.ts

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

export default ({
  : [
    ({
      : (/* 主题选项 */),
      : () => {
        // 添加你的自定义插件，并且可以控制最终的调用顺序
        return [
          ...
        ]
      }
    })
  ]
})

`llms`

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

vite.config.ts

import {  } from '@sveltepress/vite'

({
  : {
    : 'My docs',
    : 'Documentation for my project',
  },
  : {
    : true,
    : 'https://docs.example.com',
    : (, ) => . !== 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 {  } from '@sveltepress/vite'

({
  : false,
})

({
  : { : 'config/document-versions.json' },
})

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

多语言、Pagefind 与 locale hooks

`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  = <typeof sveltekit>[0]

export type  = Plugin<[], any>

export type  = (: string, : , ?: string) => string | <string>

export type  = [] | ((: ) => <[]>) | ((: ) => [])

export interface SiteConfig {
 ?: string
 ?: string

`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 {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : (/* 默认主题选项 */),
      : [/* 你的 remark 插件 */]
    })
  ]
})

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

`footnoteLabel`

自定义脚注标题，默认为："Footnotes"

虚拟模块

`virtual:sveltepress/site`

这个模块默认导出 siteConfig，示例：

站点标题为：Sveltepress

站点描述：A content centered site build tool

<script>
  import  from 'virtual:sveltepress/site'
</script>

<p>站点标题为：{.}</p>
<p>站点描述：{.}</p>

svelte

更低层级的 markdown API

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

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

import {  } from '@sveltepress/vite'

const  = `
---
title: Foo
---
<script>
  const foo = 'bar'
</script>
# Title

foo in script is: {foo}

[Foo Link](https://foo.bar)
`

const { ,  } = await ({
  : ,
  : [], // 自定义 remark 插件
  : [], // 自定义 rehype 插件
  : async (, , ) => .('高亮后的 HTML 结果'), // 自定义代码高亮函数
  : 'Foo.svelte', // 虚拟文件路径
})

// 渲染后的 Svelte 代码


// 解析后的 frontmatter 对象，这里是： { title: 'Foo' }

按字面量准备代码块

`@sveltepress/vite/highlight`

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

import {  } from '@sveltepress/vite/highlight'

const  = (
  '// @noErrors\nconst value = 1 ',
  'title="source.md" ln',
  { : 'literal' },
)

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

Typescript

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

/src/app.d.ts

/// <reference types="@sveltepress/vite/types" />

// Your other types

在 Github 上编辑此页

最后更新于： 2026/09/05 03:57