svedocs

Integrated SvelteKit documentation framework package.

Exports

• svedocs/config: config schema and defineConfig.
• svedocs/core: content manifest, scoped navigation, checks, search records, and shared types.
• svedocs/vite: virtual modules and content refresh Vite plugin.
• svedocs/theme: default Svelte theme components, replaceable theme component map, and Tailwind CSS v4 styles.
• svedocs/theme/headless: unstyled theme behavior controllers for custom themes.
• svedocs/theme/types: public theme component prop and component-map types.
• svedocs/svelte: mdsvex-based Svelte-compatible authoring helpers.
• svedocs/search: weighted local search, scope filters, Cloudflare AI Search provider, and indexing sync.
• svedocs/ai: Ask AI providers, SSE responses, and rate limiting helpers.
• svedocs/og: SEO metadata, sitemap/robots, opt-in RSS, SVG/PNG/Satori OG generation.
• svedocs/cloudflare: build presets, wrangler config, and binding type helpers.
• svedocs/integrations: IndexNow submissions and assets, Google Ads conversion helpers, and integration types.

All rendering, theme, search, AI, SEO, OG, Cloudflare, and optional service integrations are intentionally kept inside this package.

Optional service integrations

Configure integrations.umami, googleAnalytics, googleAds, googleAdsense, or indexNow in svedocs.config.ts. All are off by default. DocsApp handles analytics and client navigation; the default article supports named AdSense placements. Custom themes can use Integrations, GoogleAd, and GoogleAdsConversion from svedocs/theme.

The Vite plugin emits IndexNow verification files and AdSense ads.txt assets. After deploying, run svedocs indexnow --dry-run to inspect the submission or svedocs indexnow to send it. See the integration guide for configuration, GA4 pageview settings, and build-mode details.

Theme Development

The default theme is optional and replaceable. Import the full bundled CSS when you want the standard look:

<script lang="ts">
  import 'svedocs/theme/styles.css';
</script>

Custom themes can import only svedocs/theme/base.css for reset, accessibility, prose, and code structure, or skip theme CSS entirely and own every style.

Register replacement components in the Vite plugin, not svedocs.config.ts, because Svelte component paths are build-time imports:

import { svedocs } from 'svedocs/vite';
import svedocsConfig from './svedocs.config';

svedocs({
  config: svedocsConfig,
  theme: {
    components: {
      Navbar: '$lib/theme/Navbar.svelte',
      Article: '$lib/theme/Article.svelte',
      Search: '$lib/theme/Search.svelte',
      AskAi: '$lib/theme/AskAi.svelte',
      Error: '$lib/theme/Error.svelte'
    }
  }
});

Generated routes import virtual:svedocs/theme-components and pass the map to DocsApp. You can replace broad page layouts such as Root, Layout, Docs, Page, Home, and Error, or smaller pieces such as Navbar, Sidebar, Article, Toc, Search, AskAi, Footer, ThemeToggle, PageTools, and RenderError.

Use svedocs/theme/types for stable props and svedocs/theme/headless for unstyled behavior controllers such as search, Ask AI, ToC tracking, theme mode, mobile nav, page tools, and code-copy behavior. Replacement page layouts should keep passing pages, tree, search, config, loadSearch, and themeComponents into nested default components so navigation highlighting, mobile menus, and runtime panels stay connected.

Generated templates include src/routes/+error.svelte. Register theme.components.Error to customize full-route error pages and theme.components.RenderError to customize local render-boundary failures inside layouts, articles, and tools.

MDX/SVX Components

The Vite plugin loads svedocs.config.ts by default. You can also pass a config object explicitly and register shared authoring components or layouts:

import { svedocs } from 'svedocs/vite';
import svedocsConfig from './svedocs.config';

svedocs({
  config: svedocsConfig,
  components: {
    Callout: '$lib/Callout.svelte'
  },
  layouts: {
    feature: '$lib/FeatureLayout.svelte'
  },
  theme: {
    components: {
      Navbar: '$lib/theme/Navbar.svelte',
      Article: '$lib/theme/Article.svelte'
    }
  }
})

.svx and .mdx files can then use <Callout /> without local imports. Registered theme components are exposed through virtual:svedocs/theme-components and can replace default navigation, article, search, Ask AI, ToC, and footer rendering.

Image optimization

Local raster images in Markdown, MDX, and SVX are optimized by default with an 880px maximum width and WebP output. Configure images in svedocs.config.ts to change maxWidth, quality, format (original, webp, or avif), or outputDir; set images: false to disable it. Remote/CDN URLs are never rewritten. Use a no-compress title, a no-compress/no-optimize/unoptimized class or data attribute, or page frontmatter imageCompression: false to skip optimization.

Custom Svelte layouts and landing pages can use SvedocsImage from svedocs/theme. Static local src values are optimized by the Vite plugin at build time, using the same width and format settings as content images; dynamic and remote URLs are rendered unchanged. Use displayWidth when the preferred optimization width differs from the rendered width.