Vite plugin

Types overview

import type {  } from '@sveltejs/kit/vite'
import type {  } from 'shiki/langs'
import type {  } from 'unified'
import type {  } from 'vite'

/**
 * The options accepted by SvelteKit's `sveltekit()` vite plugin.
 *
 * 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
 * server with duplicated Svelte compilation).
 */
export type  = <typeof >[0]

export type  = <[], any>

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

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

export interface SiteConfig {
  ?: string
  ?: string
}
export interface ResolvedTheme {
  : string
  : string
  : string
  : 
  : 
  ?: []
  ?: []
  /**
   * The footnote label used for [remark rehype](https://github.com/remarkjs/remark-rehype#api)
   */
  ?: string
  /** Receive the core version configuration before theme plugins are resolved. */
  ?: (: ) => void
}

export type  = SveltepressVitePluginOptions['versions']

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

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

export interface PageInfo {
  : string
  : string
  : string
  : <string, unknown>
}

/**
 * A single locale of a multi-locale site. Keyed by its URL prefix (`'/'` for
 * the default locale, `'/zh/'`, `'/bn/'`, ...).
 */
export interface < = any> {
  /** BCP 47 language tag, e.g. `'en'`, `'zh-CN'`, `'bn'`. */
  : string
  /** User-facing label rendered in the language switcher. */
  : string
  /** The locale's full theme options. */
  : 
  /**
   * Logical routes available in this locale (no locale prefix). Populated by
   * the core plugin from the routes directory; only needed explicitly when
   * constructing configs directly.
   */
  ?: string[]
}

/** Multi-locale site configuration keyed by URL prefix. */
export type < = any> = <string, <>>

/** A locale resolved from a route: the locale config plus its matched prefix. */
export interface < = any> extends <> {
  /** The locale's URL prefix, e.g. `'/'`, `'/zh/'`. */
  : string
}

/** The target of a locale switch. */
export interface LocaleSwitchTarget {
  : string
  /** Whether the target locale lacks the logical page and the href falls back to its home. */
  : boolean
}

/**
 * Slim per-locale version snapshot used by the language switcher. Only the
 * fields needed to keep the same frozen version (and fall back otherwise)
 * are required; full manifests stay on `virtual:sveltepress/versions`.
 */
export interface LocaleVersionSnapshot {
  : string
  : { : string, ?: string[] }
  : <{ : string, ?: string[] }>
}

export interface LlmsConfig {
  ?: boolean
  ?: string
  ?: string
  ?: string
  ?: string
  ?: (: string, : <string, unknown>) => boolean
  ?: (: PageInfo, : PageInfo) => number
}

export interface SveltepressVitePluginOptions {
  ?: ResolvedTheme
  ?: SiteConfig
  ?: boolean
  ?: [] | 
  ?: [] | 
  ?: LlmsConfig
  /**
   * Multi-locale site configuration keyed by URL prefix (`'/'` for the default
   * locale, `'/zh/'`, `'/bn/'`, ...). Each entry carries that locale's `lang`,
   * a user-facing `label` for the switcher, and its full theme options.
   *
   * When omitted the site stays single-locale and behavior is unchanged.
   */
  ?: 
  /**
   * Enable document version management by discovering
   * `sveltepress.versions.json`, override its location, or disable discovery.
   */
  ?: false | {
    ?: string
  }
  /**
   * 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.
   */
  ?: 
  /**
   * Options for Pagefind static local search indexing.
   * Set to `false` to disable automatic post-build indexing.
   */
  ?: boolean | import('./pagefind.js').PagefindOptions
}

export type < = any> = (?: ) => ResolvedTheme

export type  = <any[], any> | [<any[], any>, any]

export type  = <>
ts
Expand code

Plugin options

siteConfig

  • title: The site's title. Would be 'Untitled site' if not provided.
  • description: The site's description. Would be 'Build by sveltepress' if not provided.

addInspect

If set to true, will add Vite plugin inspect . It is useful to inspect or observe the Vite pipeline.

theme

See ResolvedTheme below

remarkPlugins

The remark plugins used for markdown parse. Read Remark plugins for more details.

Customize remark/rehype plugins order

The remarkPlugins and rehypePlugins can be one of these two format:

  1. An array of Plugins. The plugins provided here will run after theme provide remark plugins.
  2. A function that accept the themeRemarkPlugins then return an array of Plugins, for example:
vite.config.ts
import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : (/* theme options */),
      : () => {
        // Add your custom plugin. Feel free to control the final order to apply all the plugins
        return [
          ...
        ]
      }
    })
  ]
})
ts

rehypePlugins

The rehype plugins used for html generator. Read Rehype plugins for more details.

llms

Generate machine-readable documentation indexes during production builds. It is disabled by default.

vite.config.ts
import {  } from '@sveltepress/vite'

({
  : {
    : 'My docs',
    : 'Documentation for my project',
  },
  : {
    : true,
    : 'https://docs.example.com',
    : (, ) => . !== false,
  },
})
ts
OptionTypeDefaultPurpose
enabledbooleanfalseWrite llms.txt and llms-full.txt during a build.
titlestringsiteConfig.titleTitle used in both generated files.
descriptionstringsiteConfig.descriptionDescription used in both generated files.
baseUrlstring''Absolute site origin prepended to route links.
routesDirstring'src/routes'Directory scanned for pages.
filter(filePath, frontmatter) => booleanExclude selected pages.
sort(a, b) => numberroute pathCustomize page order.

The generator reads Markdown pages only; Svelte-only pages and runtime data are not included. With incremental document versions, historical indexes read each page's frozen Markdown artifact rather than current source. Builds write the files into both static/ and the production bundle so a clean CI build includes them in the deployed output. Decide whether to commit the static/ copies or ignore and regenerate them consistently in CI.

Version change discovery

versions

Document version management is discovered from sveltepress.versions.json by default. Disable discovery or choose another manifest path explicitly:

import {  } from '@sveltepress/vite'

({
  : false,
})

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

When enabled, virtual:sveltepress/versions exports changeSets and resolveVersionChanges(versionId?) alongside the manifest and route helpers. See Document version management for snapshot and What’s New usage.

ResolvedTheme

name

The name of the theme.

globalLayout

The absolute path of the global layout. Should be a svelte file For example: path.resolve(process.cwd(), 'ThemeGlobalLayout.svelte')

pageLayout

The absolute path of the page layout. Should be a svelte file For example: path.resolve(process.cwd(), 'ThemePageLayout.svelte')

vitePlugins

  • If passed a plugin or a group of plugins, these plugins would applied in before sveltepress
  • If passed a function, it will accept the sveltepress plugin and need to return a group of plugins. You can customize the sveltepress plugin order in your returned plugin chain.
About theme vite plugins

It maybe a little strange that theme has vite plugins. But it is useful when the theme want's to add some virtual modules or write some temp files.

highlighter

Used for code highlighting. For example, the default theme use Shiki . You can check the default theme highlighter source code for detailed usage.

remarkPlugins

The remark plugins used for Markdown parsing. Read Remark plugins for more details.

rehypePlugins

The rehype plugins used for HTML generation. Read Rehype plugins for more details.

Plugins order

The remark and rehype plugins that theme provide would be called before the plugins provide by vite plugin. For example:

vite.config.(js|ts)
import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : (/* theme options */),
      : [/* yourRemarkPlugin */]
    })
  ]
})
ts

yourRemarkPlugin would run after the remark plugins in defaultTheme

footnoteLabel

Customize the footnotes title, default is: "Footnotes"

Virtual modules

virtual:sveltepress/site

This module holds the siteConfig. For example:

The site title is: Sveltepress

The site description is: A content centered site build tool

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

<p>The site title is: {.}</p>
<p>The site description is: {.}</p>
svelte
View code

Low level API

The @sveltepress/vite package has a low level function mdToSvelte.

It is used for all the major Markdown rendering in Sveltepress.

It can be used for a more basic Markdown render engine involved with Svelte.

Here's usage example:

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 ({
  ,
  : [], // your custom remark plugins
  : [], // your custom rehype plugins
  : async (, , ) => .('The rendered highlighted code html'), // your custom code highlighter
  : 'foo.md', // the virtual file path
})

// The rendered svelte code


// The frontmatter object, { title: 'Foo' }
ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Literal code-block preparation

@sveltepress/vite/highlight

Import prepareCodeBlock from @sveltepress/vite/highlight and pass { mode: 'literal' } as its third argument when the source must not be transformed. Code commands such as // [svp! hl] and a leading // @noErrors remain unchanged in processedCode, while metadata parsing still resolves title and ln.

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

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

Here prepared.processedCode equals the input, prepared.title is 'source.md', and prepared.containLineNumbers is true. prepared.noErrors remains false because literal mode preserves @noErrors instead of processing it as a directive.

Working with TypeScript

You need to include @sveltepress/vite/types in your src/app.d.ts to get plugin options and virtual module's type tips

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

// Your other types
ts