Vite plugin

Types overview

import type { BundledLanguage  } from 'shiki/langs'
import type { Plugin  } from 'unified'
import type { PluginOption  } from 'vite'

export type RemarkLiveCode  = Plugin <[], any>

export type Highlighter  = (code : string, lang : BundledLanguage , meta ?: string) => string | Promise <string>

export type ThemeVitePlugins  = PluginOption [] | ((corePlugin : PluginOption ) => Promise <PluginOption []>) | ((corePlugin : PluginOption ) => PluginOption [])

export interface SiteConfig {
  title ?: string
  description ?: string
}
export interface ResolvedTheme {
  name : string
  globalLayout : string
  pageLayout : string
  vitePlugins : ThemeVitePlugins 
  highlighter : Highlighter 
  remarkPlugins ?: Plugin []
  rehypePlugins ?: Plugin []
  /**
   * The footnote label used for [remark rehype](https://github.com/remarkjs/remark-rehype#api)
   */
  footnoteLabel ?: string
}

export type RemarkPluginsOrderer  = ((themeRemarkPlugins : Plugin []) => Plugin [])

export type RehypePluginsOrderer  = ((themeRehypePlugins : Plugin []) => Plugin [])

export interface SveltepressVitePluginOptions {
  theme ?: ResolvedTheme
  siteConfig ?: SiteConfig
  addInspect ?: boolean
  remarkPlugins ?: Plugin [] | RemarkPluginsOrderer 
  rehypePlugins ?: Plugin [] | RehypePluginsOrderer 
}

export type LoadTheme <ThemeOptions  = any> = (themeOptions ?: ThemeOptions ) => ResolvedTheme

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

export type AcceptableRemarkPlugin  = Array <RawRemarkPlugin >

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.

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

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

rehypePlugins

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

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.

highlighter

Used for code highlighting. For example, the default theme use Shiki . You can check the Default theme highlighter source code for detail 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.

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

export default defineConfig ({
  plugins : [
    sveltepress ({
      theme : defaultTheme (/* theme options */),
      remarkPlugins : [/* yourRemarkPlugin */]
    })
  ]
})

footnoteLabel

Customize the footnotes title, default is: "Footnotes"

Virtual modules

virtual:sveltepress/site

This module holds the siteConfig. For example:

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

<p>The site title is: {siteConfig .title }</p>
<p>The site description is: {siteConfig .description }</p>

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 { mdToSvelte  } from '@sveltepress/vite'

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

foo in script is: {foo}

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

const { code , data  } = await mdToSvelte ({
  mdContent ,
  remarkPlugins : [], // your custom remark plugins
  rehypePlugins : [], // your custom rehype plugins
  highlighter : async (code , lang , meta ) => Promise .resolve ('The rendered highlighted code html'), // your custom code highlighter
  filename : 'foo.md', // the virtual file path
})

// The rendered svelte code
code 

// The frontmatter object, { title: 'Foo' }
data 

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

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

// Your other types