Default theme

Install

npm install --save @sveltepress/theme-default

Add in your Vite config

vite.config.(js|ts)

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

Types Overview

/// <reference types="vite/client" />
/// <reference types="@sveltepress/vite/types" />
/// <reference types="@sveltejs/kit/vite" />

declare module 'virtual:sveltepress/theme-default' {
  import type {  } from '@sveltepress/docsearch/types'
  import type {  } from '@sveltepress/twoslash'
  import type {  } from '@sveltepress/vite'
  import type {  } from '@vite-pwa/sveltekit'
  import type {  } from 'shiki'
  import type {  } from 'shiki/langs'
  import type {  } from 'svelte'

  export interface WithTitle {
    ?: string
  }

  export interface LinkItem extends WithTitle {
    ?: string
    ?: string
    ?: boolean
    ?: boolean
    ?: LinkItem[]
  }

  export interface AutoSidebarOptions {
    /**
     * Enable auto-generated sidebar
     */
    : boolean
    /**
     * Routes directory, default 'src/routes'
     */
    ?: string
    /**
     * Root paths to generate sidebar for, e.g. ['/guide/', '/reference/']
     * If not specified, auto-detect from top-level route directories
     */
    ?: string[]
  }

  export interface DefaultThemeOptions {
    ?: <LinkItem>
    ?: string
    ?: string
    ?: <string, LinkItem[]> | AutoSidebarOptions
    ?: string
    ?: string
    ?: string
    ?:  & {
      ?: string
    }
    ?: <, 'container' | 'theme'>
    ?:  | string
    ?: {
      : string
      : string
      ?: string
      ?: string
      ?: {
        : string
        : string
      }
    }
    ?: {
      ?: []
      ?: 
      ?: 
      ?: boolean | 
    }
    ?: {
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: string
      ?: {
        ?: string
        ?: string
        ?: string
        ?: string
        ?: string
      }
      ?: string
    }
    ?: {
      [: string]: string[]
    }
  }
  export type  = <DefaultThemeOptions>

  const : DefaultThemeOptions
  export default 
}

declare module '@sveltepress/theme-default/context' {
  import type {  } from 'svelte/store'

  export interface SveltepressContext {
    : <boolean>
  }
  export const : symbol
}

Theme Options

`navbar`

title The label text of the item in the navigation bar.
to The link address
icon An HTML string. Will show the html content instead of title. It is useful to display a custom icon on the navbar.
external Determine whether the link is external or not. Would render an external icon if set to true
items Children links. If this prop is provided it would render a dropdown instead of a single link.

`discord`

The web invite address to the project's Discord server. Would show a discord icon on the navigation bar when provided.

`github`

The web address of the project's GitHub repository. Would show a GitHub icon on the navigation bar when provided

`logo`

The address of the site's logo, to be shown on the navigation bar.

`sidebar`

The sidebar can be configured in two ways:

Auto-generated sidebar

Pass an object with enabled: true to automatically generate the sidebar from your routes directory.

enabled - Set to true to enable auto sidebar generation
routesDir - Custom routes directory path. Default is 'src/routes'
roots - Root paths to generate sidebar for, e.g. ['/guide/', '/reference/']. If not specified, auto-detected from top-level route directories

Pages can control their sidebar appearance via frontmatter:

title - Page title, also used as sidebar label
sidebarTitle - Override the sidebar label (takes precedence over title)
order - Sort order within the same level. Lower numbers appear first. Default is 100
sidebar - Set to false to exclude this page from the sidebar
collapsible - Whether the sidebar group is collapsible

Manual sidebar

Pass an object where each key is a group route prefix and each value is an array of sidebar items:

title The label text of the sidebar item
collapsible Determine whether the sidebar group is collapsible or not.
to The link address
items Children links. If this prop is provided would render a sidebar group instead of a single sidebar item

`highlighter`

An object that contains custom highlight options.

languages - Customize the supported highlight languages. Default is: ['svelte', 'sh', 'js', 'html', 'ts', 'md', 'css', 'scss']
themeLight - The code theme that will be applied in light mode. Default is vitesse-light
darkTheme - The code theme that will be applied in dark mode. Default is night-owl
twoslash - Set to true to enable Twoslash . Default is false

TIP

You can get all the supported languages and themes in Shiki Repo

`editLink`

The link used for bottom edit this page on GitHub button For example this site use https://github.com/Blackman99/sveltepress/edit/main/packages/docs-site/src/routes/:route

:route represent the route path, for example: /foo/bar/+page.md

`ga`

The id provided by Google Analytics . Something like G-XXXXXXX.

Would add gtag script in site head if provided.

`search`

Custom search component for the navbar.

Type: Component | string
If a Component is provided, it is rendered directly.
If a string is provided, it is treated as a component path and loaded via dynamic import().

Examples:

// Use Meilisearch
search: '@sveltepress/meilisearch/Search.svelte'

// Or a custom component
search: '/src/lib/MySearch.svelte'

search vs docsearch priority

When both search and docsearch are provided, search takes priority and docsearch is ignored.

`docsearch`

appId
apiKey
indexName

All these values are provided by Algolia. Visit Docsearch for more details.

docsearch is used only when search is not provided.

`pwa`

See PWA for details.

`themeColor`

The color of window bar when opened as a local PWA application.

light - the color that applied on light theme
dark - the color that applied on dark theme
gradient - the gradient theme color. Would be applied on home page action button and main title. Default is:

const defaultGradient = {
  start: '#fa709a',
  end: '#fee140',
}

primary - the primary theme color of the site
hover - the hovered links color

`i18n`

The fixed text contents that can be replaced by your config.

onThisPage - The text for "On this page"
suggestChangesToThisPage - The text for "Suggest changes to this page"
lastUpdateAt - The text for "Last update at:"
previousPage - The text for "Previous"
nextPage - The text for "Next"
expansionTitle - The text for "Click to expand/fold code" in markdown or svelte live code
pwa - The PWA prompt relative text contents. All of the following fields correspond to the same text in PWA prompt
- tip
- reload
- close
- appReadyToWorkOffline
- newContentAvailable
footnoteLabel - The auto generated footnotes title. Default is "Footnotes"

`preBuildIconifyIcons`

The icons in Iconify that you want to pre-build for future usage. An object, key is the collection name, value is the icons array. For example these are the icons this site using:

preBuildIconifyIcons: {
  'vscode-icons': ['file-type-svelte', 'file-type-markdown', 'file-type-vite'],
  'logos': ['typescript-icon', 'svelte-kit'],
  'emojione': ['artist-palette'],
  'ph': ['smiley', 'layout-duotone'],
  'noto': ['package'],
  'solar': ['chat-square-code-outline', 'reorder-outline'],
  'carbon': ['tree-view-alt', 'import-export'],
  'ic': ['sharp-rocket-launch'],
  'tabler': ['icons'],
  'mdi': ['theme-light-dark'],
  'bi': ['list-nested'],
}

These icons looks like this:

<script>
  import {  } from '@sveltepress/theme-default/components'
  import  from 'virtual:sveltepress/theme-default'
</script>
<div class="flex items-center gap-4 text-[48px] flex-wrap">
  {#each .(. || {}) as [, ]}
    {#each  as }
      <div>
        <} {} />
      </div>
    {/each}
  {/each}
</div>

svelte

Global context

The global context key is in the @sveltepress/theme-default/context. You can get all the contexts with the getContext API

This is an example:

isDark: false

<script lang="ts">
  import type { SveltepressContext } from '@sveltepress/theme-default/context'
  import {  } from '@sveltepress/theme-default/context'
  import {  } from 'svelte'

  const {  } = <SveltepressContext>(
</script>

<div class:dark-text={} class="text-10">
  isDark: {}
</div>
<style>
  .dark-text {
    --at-apply: 'text-red';
  }
</style>

svelte

All contexts:

$isDark - Determine the current theme is dark or not. It is a reactive svelte store .

Virtual modules

`virtual:sveltepress/theme-default`

This module hold the theme options that pass to defaultTheme() function.

Here's an example for showing the theme options of this site:

    {
  "navbar": [
    {
      "title": "Guide",
      "to": "/guide/introduction/"
    },
    {
      "title": "Reference",
      "to": "/reference/vite-plugin/"
    },
    {
      "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M27.85 29H30l-6-15h-2.35l-6 15h2.15l1.6-4h6.85zm-7.65-6l2.62-6.56L25.45 23zM18 7V5h-7V2H9v3H2v2h10.74a14.71 14.71 0 0 1-3.19 6.18A13.5 13.5 0 0 1 7.26 9h-2.1a16.47 16.47 0 0 0 3 5.58A16.84 16.84 0 0 1 3 18l.75 1.86A18.47 18.47 0 0 0 9.53 16a16.92 16.92 0 0 0 5.76 3.84L16 18a14.48 14.48 0 0 1-5.12-3.37A17.64 17.64 0 0 0 14.8 7z\"/></svg>",
      "items": [
        {
          "title": "简体中文",
          "to": "https://cn.sveltepress.site/",
          "external": true
        },
        {
          "title": "বাংলা",
          "to": "https://bn.sveltepress.site/",
          "external": true
        }
      ]
    }
  ],
  "sidebar": {
    "/guide/": [
      {
        "title": "Introduction",
        "collapsible": true,
        "items": [
          {
            "title": "What is Sveltepress",
            "to": "/guide/introduction/"
          },
          {
            "title": "Quick Start",
            "to": "/guide/quick-start/"
          },
          {
            "title": "Themes",
            "to": "/guide/themes/"
          },
          {
            "title": "Working with TypeScript",
            "to": "/guide/typescript/"
          }
        ]
      },
      {
        "title": "Markdown features",
        "items": [
          {
            "title": "Basic Writing",
            "to": "/guide/markdown/basic-writing/"
          },
          {
            "title": "Frontmatter",
            "to": "/guide/markdown/frontmatter/"
          },
          {
            "title": "Svelte in Markdown",
            "to": "/guide/markdown/svelte-in-markdown/"
          }
        ]
      },
      {
        "title": "Default theme features",
        "collapsible": true,
        "items": [
          {
            "title": "Frontmatter",
            "to": "/guide/default-theme/frontmatter/"
          },
          {
            "title": "Navbar",
            "to": "/guide/default-theme/navbar/"
          },
          {
            "title": "Sidebar",
            "to": "/guide/default-theme/sidebar/"
          },
          {
            "title": "Home page",
            "to": "/guide/default-theme/home-page/"
          },
          {
            "title": "Built-in Components",
            "to": "/guide/default-theme/builtin-components/"
          },
          {
            "title": "Headings & Anchors",
            "to": "/guide/default-theme/headings-and-anchors/"
          },
          {
            "title": "Admonitions",
            "to": "/guide/default-theme/admonitions/"
          },
          {
            "title": "Code related",
            "to": "/guide/default-theme/code-related/"
          },
          {
            "title": "Twoslash",
            "to": "/guide/default-theme/twoslash/"
          },
          {
            "title": "Unocss",
            "to": "/guide/default-theme/unocss/"
          },
          {
            "title": "Search",
            "to": "/guide/default-theme/search/"
          },
          {
            "title": "PWA",
            "to": "/guide/default-theme/pwa/"
          },
          {
            "title": "Google Analytics",
            "to": "/guide/default-theme/google-analytics/"
          }
        ]
      }
    ],
    "/reference/": [
      {
        "title": "Reference",
        "items": [
          {
            "title": "Vite plugin",
            "to": "/reference/vite-plugin/"
          },
          {
            "title": "Default theme",
            "to": "/reference/default-theme/"
          }
        ]
      }
    ]
  },
  "editLink": "https://github.com/Blackman99/sveltepress/edit/main/packages/docs-site/src/routes/:route",
  "github": "https://github.com/Blackman99/sveltepress",
  "logo": "/sveltepress.svg",
  "discord": "https://discord.gg/MeYRrGGxbE",
  "ga": "G-J2W78BKCHB",
  "docsearch": {
    "apiKey": "fbed412316ec83ff28e9a916161bf715",
    "appId": "4D30VFIAMG",
    "indexName": "sveltepress"
  },
  "pwa": {
    "scope": "/",
    "base": "/",
    "strategies": "generateSW",
    "kit": {
      "trailingSlash": "always"
    },
    "darkManifest": "/manifest-dark.webmanifest",
    "manifest": {
      "start_url": "/",
      "scope": "/",
      "name": "Sveltepress",
      "short_name": "Sveltepress",
      "icons": [
        {
          "src": "/android-chrome-192x192.png",
          "sizes": "192x192",
          "type": "image/png"
        },
        {
          "src": "/android-chrome-512x512.png",
          "sizes": "512x512",
          "type": "image/png"
        }
      ],
      "theme_color": "#f2f2f2",
      "background_color": "#f2f2f2",
      "display": "standalone"
    }
  },
  "themeColor": {
    "light": "#f2f2f2",
    "dark": "#18181b"
  },
  "preBuildIconifyIcons": {
    "vscode-icons": [
      "file-type-svelte",
      "file-type-markdown",
      "file-type-vite"
    ],
    "logos": [
      "typescript-icon",
      "svelte-kit"
    ],
    "emojione": [
      "artist-palette"
    ],
    "ph": [
      "smiley",
      "layout-duotone"
    ],
    "noto": [
      "package"
    ],
    "solar": [
      "chat-square-code-outline",
      "reorder-outline"
    ],
    "carbon": [
      "tree-view-alt",
      "import-export"
    ],
    "ic": [
      "sharp-rocket-launch"
    ],
    "tabler": [
      "icons"
    ],
    "mdi": [
      "theme-light-dark"
    ],
    "bi": [
      "list-nested"
    ]
  },
  "highlighter": {
    "twoslash": true,
    "languages": [
      "svelte",
      "sh",
      "js",
      "html",
      "ts",
      "md",
      "css",
      "scss",
      "json"
    ]
  }
}

<script>
  import  from 'virtual:sveltepress/theme-default'
</script>
<div class="viewer">
  <pre>
    {.(, null, 2)}
  </pre>
</div>
<style>
  .viewer {
    max-height: 40vh;
    overflow-y: auto;
    overflow-x: hidden;
  }
</style>

svelte

Working with TypeScript

You need to include @sveltepress/theme-default/types in your src/app.d.ts to get theme options and virtual modules type tips

/src/app.d.ts

/// <reference types="@sveltepress/theme-default/types" />

// Your other types

Suggest changes to this page

Last update at: 2026/03/19 07:24:06