Sveltepress

环境要求

  • Node.js ^20.19.0 或 >=22.12.0
  • Svelte 5、SvelteKit 2 和 Vite 8
  • 推荐 pnpm 10；创建命令同时支持 npm、Yarn 和 Bun

创建一个项目

根据您所使用的包管理工具选择运行以下命令：

npm create @sveltepress@latest
sh
yarn create @sveltepress@latest
sh
pnpm create @sveltepress@latest
sh
bun create @sveltepress@latest
sh
pnpm 优先

仓库与生成模板均使用 pnpm 10 验证。

添加到一个已经存在的 Sveltekit 项目

安装 Vite 插件

npm install --save @sveltepress/vite
sh
yarn add @sveltepress/vite
sh
pnpm install @sveltepress/vite
sh
bun add @sveltepress/vite
sh

在 vite.config.(js|ts) 中替换 sveltekit 插件

vite.config.(js|ts)
-
+
-
+
import { function sveltekit(config?: KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">): Promise<Plugin[]>
Returns the SvelteKit Vite plugins.
Since version 2.62.0 you can pass configuration directly, in which case svelte.config.js is ignored.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte.
sveltekit } from '@sveltejs/kit/vite' 

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[] | undefined
Array of vite plugins to use.
plugins: [
    function sveltekit(config?: KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">): Promise<Plugin[]>
Returns the SvelteKit Vite plugins.
Since version 2.62.0 you can pass configuration directly, in which case svelte.config.js is ignored.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte.
sveltekit(), 
    function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress(), 
  ],
})

export default const config: UserConfigconfig
ts
请移除原来的 sveltekit() 插件

sveltepress() 已经为你配置好了 SvelteKit。如果在 plugins 中同时保留 sveltekit() 和 sveltepress()，每个 Svelte 文件都会被编译两次，导致开发服务器崩溃并报错 Expected token }。

在 svelte.config.js 中添加 '.md' 到 extensions 选项

svelte.config.js
-
+
import function adapter(options?: AdapterOptions): Adapteradapter from '@sveltejs/adapter-static'
import { function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess } from '@sveltejs/vite-plugin-svelte'

/**
 * @type {import('@sveltejs/kit').Config}
 */
const 

const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
    };
}
@type{import('@sveltejs/kit').Config}
config = {
  extensions: string[]extensions: ['.svelte'], 
  extensions: string[]extensions: ['.svelte', '.md'], // add .md here 
  preprocess: PreprocessorGroup[]preprocess: [function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess()],
  

kit: {
    adapter: Adapter;
}
kit: {
    adapter: Adapteradapter: function adapter(options?: AdapterOptions): Adapteradapter({
      AdapterOptions.pages?: string | undefinedpages: 'dist',
    }),
  },
}

export default 

const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
    };
}
@type{import('@sveltejs/kit').Config}
config
ts
没有 svelte.config.js？（较新的 SvelteKit 项目结构）

使用较新的 npx sv create 创建的项目会把 SvelteKit 配置直接内联写在 vite.config.ts 中，且不再包含 svelte.config.js。请将这些配置移动到 sveltepress({ svelteKitOptions }) 中（Sveltepress 会自动帮你加上 '.md' 扩展名），并移除单独的 sveltekit() 插件：

vite.config.ts
import import adapteradapter from '@sveltejs/adapter-auto'
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.svelteKitOptions?: (KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">) | undefined
Options forwarded to the SvelteKit vite plugin that sveltepress() sets up
internally.


Use this on the newer SvelteKit layout (no svelte.config.js, config passed
inline to sveltekit()) to move your compilerOptions, adapter, etc. into
sveltepress() and remove the standalone sveltekit() plugin. '.md' is
always added to extensions automatically.


When omitted, SvelteKit reads its config from svelte.config.js as before.
svelteKitOptions: {
        compilerOptions?: Omit<CompileOptions, "filename" | "format" | "generate"> | undefined
The options to be passed to the Svelte compiler. A few options are set by default,
including dev and css. However, some options are non-configurable, like
filename, format, generate, and cssHash (in dev).
@seehttps://svelte.dev/docs/svelte/svelte-compiler#CompileOptions
compilerOptions: {
          

runes?: boolean | ((options: {
    filename: string;
}) => boolean | undefined) | undefined
Set to true to force the compiler into runes mode, even if there are no indications of runes usage.
Set to false to force the compiler into ignoring runes, even if there are indications of runes usage.
Set to undefined (the default) to infer runes mode from the component code.
Is always true for JS/TS modules compiled with Svelte.
Will be true by default in Svelte 6.
Note that setting this to true in your svelte.config.js will force runes mode for your entire project, including components in node_modules,
which is likely not what you want. If you're using Vite, consider using dynamicCompileOptions instead.
@defaultundefined
runes: ({ filename: stringfilename }) =>
            filename: stringfilename.

String.split(splitter: {
    [Symbol.split](string: string, limit?: number): string[];
}, limit?: number): string[] (+1 overload)
Split a string into substrings using the specified separator and return them as an array.
@paramsplitter  An object that can split a string.@paramlimit  A value used to limit the number of elements returned in the array.
split(/[/\\]/).Array<string>.includes(searchElement: string, fromIndex?: number): boolean
Determines whether an array includes a certain element, returning true or false as appropriate.
@paramsearchElement  The element to search for.@paramfromIndex  The position in this array at which to begin searching for searchElement.
includes('node_modules') ? var undefinedundefined : true,
        },
        KitConfig.adapter?: Adapter | undefined
Your adapter is run when executing vite build. It determines how the output is converted for different platforms.
@defaultundefined
adapter: import adapteradapter(),
      },
    }),
  ],
})
ts