Configuration

Package exports, the config object, and the two shell components.

Everything you wire up once: what the package exports, the config object you pass to the shell, and the two page-level components that own the site chrome. Props for the authoring components (Callout, Tabs, Badge, and the rest) live on their own pages in the Components section.

Package exports

svelte-docsmith: every component, plus defineConfig, createSearchEngine, generateSitemap, generateFeed, generateLlmsTxt, generateLlmsFullTxt, and the types. Components are documented in Components; the rest is below.
svelte-docsmith/preprocess: the mdsvex + Shiki preprocessor for svelte.config.js.
svelte-docsmith/vite: the Vite plugin (content, search, llms and changelog indexes, plus the ?source transform).
svelte-docsmith/content: the generated sidebar index, exported as docs.
svelte-docsmith/search: the generated full-text search index, exported as docs (lazy-load it; see Search).
svelte-docsmith/llms: the generated per-page markdown index, exported as docs (see SEO).
svelte-docsmith/changelog: the generated release index, exported as releases (see Changelog).
svelte-docsmith/mermaid: the diagram component, imported for you by a ```mermaid fence. You never import it directly.
svelte-docsmith/theme.css: the base style contract.
svelte-docsmith/themes/*.css: the pre-installed theme presets (see Theming).

defineConfig

Validates a DocsmithConfig and returns it unchanged, throwing a clear error on an invalid or dynamically-built config instead of rendering a blank header.

			const config = defineConfig({
	title: 'My Library',
	description: 'A short tagline, used as the default meta description.',
	url: 'https://my-library.dev',
	github: 'https://github.com/you/my-library',
	version: '1.0.0'
});

title required string

Site title, shown in the header/sidebar and as the <title> suffix.

description string

Default meta description, used for pages without their own. See SEO.

url string

Canonical site origin. Enables <link rel="canonical"> and absolute Open Graph URLs.

ogImage string

Default social-share image (absolute, or a path resolved against url).

editUrl string

Base URL for the per-page “Edit this page” link, e.g. https://github.com/you/repo/edit/main/apps/docs. Each page's source path is appended. (“Last updated” is added from git automatically.)

github string

GitHub URL; renders a link in the header when set.

version string

Version string shown in the header.

logo string

Logo image src; falls back to the built-in book mark.

nav DocsmithLink[]

Top-level header navigation links.

announcement { text, tag?, href?, external?, id?, dismissible? }

A thin bar above the header. text is required; add a tag for a leading pill (e.g. "New") and an href to link it. It's dismissible by default and stays dismissed until you change id (or the text), so bump id to re-show a new announcement.

footer { copyright?, columns?, poweredBy? }

Footer copyright line, titled link columns, and the “Powered by” toggle.

This site runs one: the thin bar above the header is config.announcement. Its id tracks the library version, so it returns after each release and stays out of the way in between. Dismiss it and it holds until the next version.

docsmith() preprocessor

From svelte-docsmith/preprocess, registered in svelte.config.js. It bundles mdsvex, Shiki, heading anchors and the page layout, so markdown compiles to real routes. Every option has a working default; pass none and it does the right thing.

docsmith() — preprocess

extensions string[] default ['.md']

File extensions compiled as markdown.

themes { light: string; dark: string } default github-light / github-dark

Shiki themes for the dual light/dark render of markdown code fences. The Vite plugin has its own themes for live example source; set both to the same pair or the two will not match.

langs string[]

Extra Shiki languages on top of the built-in set. An unknown fence language falls back to plain text rather than failing the build.

layout stringfalse

Absolute path to a custom mdsvex layout, or false for none. A custom layout must export a pre component from its module script, since code fences render through it.

lineNumbers boolean default false

Number every code block. A fence overrides it either way with showLineNumbers or noLineNumbers.

twoslash boolean default false

Enable Twoslash on fences marked twoslash. Needs the optional peer dependencies; see Code blocks.

remarkPlugins PluggableList

Extra remark plugins, appended after DocSmith's own.

rehypePlugins PluggableList

Extra rehype plugins, appended after DocSmith's own (slug, sectionize).

docsmith() Vite plugin

From svelte-docsmith/vite, added to plugins in vite.config.ts. It scans your pages into the generated indexes and serves the ?source imports that Live Examples use.

docsmith() — vite

content string default 'src/routes/docs'

Directory scanned for doc pages.

routes string default 'src/routes'

Routes root, used to derive each page's URL from its location.

themes { light: string; dark: string } default github-light / github-dark

Shiki themes for the ?source render behind Live Examples. Separate from the preprocessor's themes, because the two run from different config files; set them to the same pair or your example source will not match your code blocks.

changelog stringfalse default 'CHANGELOG.md'

Path to the changelog that feeds the release index. Point it at the package you publish, or false to skip it.

changelogPath string default '/changelog'

Route the changelog is served at. Used to build feed links and to find hand-written per-release pages.

DocsShell

The full documentation shell: header, sidebar, content area, and table of contents.

			<DocsShell {config} content={docs}>
	{@render children()}
</DocsShell>

config required DocsmithConfig

The site config (see defineConfig above).

content required DocsContentItem[]

The content index; the sidebar nav is derived from it.

children required Snippet

The rendered page.

versions ResolvedVersion[] default []

The generated version manifest. Pass it to scope the sidebar, search, prev/next, and breadcrumbs to the version being read. See Versioning.

search (versionId?: string) => Promise<SearchDoc[]>

Enable the ⌘K search palette by lazily providing the generated index, e.g. () => import('svelte-docsmith/search').then((m) => m.docs). Receives the active version id on a versioned site. See Search.

seo { title?: string; description?: string }

Override the head tags for this page (title, meta description). Doc pages get these from frontmatter automatically. See SEO.

logo Snippet

Custom logo mark for the header and mobile menu.

actions Snippet

Extra header controls, before the theme toggle.

footer Snippet

Content rendered below the page column.

pattern boolean default false

Render the decorative grid-and-glow page background.

copyPage boolean default false

Show the "Copy page" split button on doc pages (copy as Markdown, view the raw .md, or open in ChatGPT / Claude). Needs the .md endpoint. See SEO.

readingTime boolean default true

Show the estimated reading time on doc pages (computed at build time from the page's word count). Set false to hide it.

feedback boolean | ((vote: 'up' | 'down', path: string) => void)

Show the "Was this page helpful?" widget at the foot of doc pages. Pass true for the UI alone, or a callback to record votes (wire it to your analytics). Omit to hide it.

layout 'docs''page' default 'docs'

docs is the three-column shell; page is full-bleed content with the same header and footer but no sidebar or TOC.

Theming needs no setup

ThemeProvider and ThemeToggle handle light and dark with no consumer wiring. DocsShell mounts the provider internally, so you never touch mode-watcher yourself. Use ThemeProvider directly to wrap a page you build outside DocsShell.

ErrorPage

A styled 404 / error screen that keeps the site chrome (header, search, footer, theme). Drop it into a SvelteKit +error.svelte:

src/routes/+error.svelte

			<script lang="ts">
	import { docs } from 'svelte-docsmith/content';
	import { ErrorPage } from 'svelte-docsmith';
	import { siteConfig } from '$lib/site-config';
</script>

<ErrorPage config={siteConfig} content={docs} home="/docs" homeLabel="Back to the docs" />

config required DocsmithConfig

Same config as DocsShell, so the chrome matches.

content DocsContentItem[] default []

Content index, so the header/footer nav still work.

status number default page.status

HTTP status. Defaults to the current page's status.

title string default from status

Heading. Defaults to “Page not found” for 404, else “Something went wrong”.

message string default page.error.message

Body line. Defaults to the error message, then a status-appropriate default.

home string default '/'

Where the primary action links.

homeLabel string default 'Back to home'

Label of the primary action.

versions ResolvedVersion[] default []

The version manifest, same as DocsShell. Pass it so an error under an archived prefix keeps that version's search scope and noindex.

search (versionId?: string) => Promise<SearchDoc[]>

Enable the ⌘K palette on the error page (same loader as DocsShell).

Types

DocsmithConfig: the config object above.
DocsContentItem: a content-index entry with title, path, and optional section, order, description, toc.
SearchDoc / SearchResult / SearchEngine: the search index entry and the shape returned by createSearchEngine.
ResolvedVersion: one entry of the generated version manifest. See Versioning.
CalloutVariant / BadgeVariant: the intent unions for Callout and Badge.

The vendored shadcn primitives and internal helpers (the TOC engine, the clipboard utility, the markdown renderer map) are not part of the public API and may change between releases.