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, 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 index, search index, and 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/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.

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.

search () => Promise<SearchDoc[]>

Enable the ⌘K search palette by lazily providing the generated index, e.g. () => import('svelte-docsmith/search').then((m) => m.docs). 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:

			<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.

search () => 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.
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.