DOCSEARCHbyAlgolia
Submit Docs

SveltePress Documentation

website·Indexed 32 days ago

https://sveltepress.site/

SveltePress is a SvelteKit docs and blog site builder inspired by VitePress. It features a default theme with built-in local search, PWA support, internationalization (i18n), and the ability to use Svelte components directly within markdown. The toolkit includes a CLI and supports Svelte 5 and SvelteKit 2.

Tokens
18K
Snippets
101
Records
136
Agent score
58%

What's inside SveltePress

  1. Overview of Sveltepress

    Sveltepress is a documentation and blog site builder built on SvelteKit and UnoCSS, inspired by VitePress. It provides a content toolkit while maintaining the full SvelteKit surface, including SSR, adapters, server routes, and hooks. Key features include native Svelte 5 Runes support in markdown, built-in AI knowledge generation (llms.txt), and integrated search options (Pagefind, DocSearch, Meilisearch).

  2. Overview of SveltePress Blog Theme

    The Blog Theme is designed for editorial sites and chronological publications. It uses Markdown files located in src/posts and includes built-in features such as:

    • Post indexing, pagination, tags, and categories
    • RSS feeds and Open Graph images
    • Related posts and comments
    • Pagefind search UI integration

    Requirements: The Blog Theme generates a static site and requires @sveltejs/adapter-static and a Pagefind post-build step.

  3. Use built-in Local Search (Pagefind)

    SveltePress provides a zero-config Local Search powered by Pagefind. It is enabled by default and runs entirely in the browser via WebAssembly. During the production build (pnpm build), SveltePress automatically indexes static HTML pages and bundles assets into /pagefind/.

    Key Features:

    • Offline & Static: No external API keys required.
    • Multi-locale: Automatically filters queries by the active page language based on <html lang="...">.
    • Keyboard Shortcuts: Open with Cmd+K (macOS) or Ctrl+K (Windows/Linux). Navigate with Arrow keys, select with Enter, and close with Escape.
    • Development Mode: In pnpm dev, a notice is displayed explaining that the full index is only created during production builds.

  4. Automatic Table of Contents (TOC) generation

    All headings in page markdown files automatically render a Table of Contents (TOC) on the right side of the page. Multi-level headings are supported, and nested headings are indented by depth in the TOC. The active viewport section is highlighted with a guide line that updates as the user scrolls.

  5. Manage Sveltepress project structure

    Sveltepress follows the standard SvelteKit project structure but allows the use of .md files for pages and layouts. For example, src/routes/+page.md serves as the home page and src/routes/+layout.md can be used for the root custom layout. Because it preserves full SvelteKit functionality, developers can use +page.server.js, +layout.server.js, and hooks.server.js for server-side logic such as authentication or database connections.

  6. Enhance code blocks with metadata and annotations

    SveltePress extends standard Markdown code blocks with several powerful features using meta fields and special comments.
    <script>
  const msg = 'world!' // [svp! hl]
  const old = 'old'    // [svp! df:-]
  const new = 'new'    // [svp! df:+]
  const focus = 'me'   // [svp! !!]
</script>

  7. Write content using Sveltepress Markdown

    Sveltepress supports standard Markdown and extended syntax. Key supported elements include:

    • Headings: Standard # to ###### syntax.
    • Styling: Bold (**text**), Strikethrough (~one~ or ~~two~~), and Inline code (`code`).
    • Lists: Unordered lists (- or *) and Task lists (- [ ] or - [x]).
    • Tables: Standard pipe-delimited tables.
    • Footnotes: Defined with [^1] and expanded at the bottom of the page. The auto-generated footnotes title can be customized via theme.footnoteLabel in the Vite plugin configuration.
    • Emojis: Supported via colon syntax (e.g., :heart:, :pizza:).

  8. Install and configure the SveltePress Default Theme

    To use the default theme in a SveltePress project, install the @sveltepress/theme-default package and add it to the sveltepress plugin configuration in your Vite config.
    pm install @sveltepress/theme-default
    import { defaultTheme } from '@sveltepress/theme-default'
import { sveltepress } from '@sveltepress/vite'
import { defineConfig } from 'vite'

const config = defineConfig({
  plugins: [
    sveltepress({
      theme: defaultTheme({ /* theme options */ })
    })
  ],
})

export default config

  9. Enable PWA support in SveltePress

    SveltePress integrates @vite-pwa/sveltekit. To enable PWA, pass the pwa option to the default theme. You must also configure files.serviceWorker in svelte.config.js using the SERVICE_WORKER_PATH exported from @sveltepress/theme-default. Additionally, workbox-window must be added as a dev dependency to the project.
    // svelte.config.js
import adapter from '@sveltejs/adapter-static'
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
import { SERVICE_WORKER_PATH } from '@sveltepress/theme-default'

/** @type {import('@sveltejs/kit').Config} */
const config = {
  extensions: ['.svelte', '.md'],
  preprocess: [vitePreprocess()],
  kit: {
    adapter: adapter(),
    files: {
      serviceWorker: SERVICE_WORKER_PATH,
    },
  },
}

export default config

  10. Install and configure the SveltePress Default Theme

    The Default Theme is best suited for documentation, product guides, and API references. It supports SvelteKit routes written in Markdown or Svelte and integrates with Algolia DocSearch or Meilisearch.
    # Install the default theme package
npm install @sveltepress/theme-default
    // vite.config.ts
import { defaultTheme } from '@sveltepress/theme-default'
import { sveltepress } from '@sveltepress/vite'
import { defineConfig } from 'vite'

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

  11. Create a release snapshot for a new version

    To advance to a new version, you must freeze the current documentation before editing pages for the next version. Run versions build to ensure the current state is captured, then run versions create to freeze the outgoing version and set the new version ID as current. Only after this step should you add :::since markers or edits for the new version.
    # 1. Build current state
pnpm exec sveltepress versions build

# 2. Freeze current and set 8.2 as the new current version
pnpm exec sveltepress versions create 8.2 --label "8.2"

# 3. (Now edit docs and add version="8.2" markers)

# 4. Build and validate
pnpm exec sveltepress versions build
pnpm exec sveltepress versions validate

  12. Enable incremental artifacts for versioned builds

    Incremental artifacts replace full snapshot directories with source deltas and a content-addressed page store in .sveltepress/version-artifacts. This acts as a build cache to speed up production builds. Use the migrate command to convert existing snapshot directories or initialize new sites.
    pnpm exec sveltepress versions migrate --site-id docs-example