Installation

You can generate a new project or add svedocs to an existing SvelteKit app. For a new site, the template is usually faster because it already contains the routes, config, content folders, and server endpoints.

Requirements

• Node.js 20.19 or newer.
• A SvelteKit project using ESM.
• pnpm, npm, yarn, or bun. The templates default to pnpm because the repository itself uses pnpm.

Create a new project

Shell
1pnpm create svedocs my-docs --template docs2cd my-docs3pnpm install4pnpm dev

The create-svedocs package forwards the command to svedocs-cli. The CLI downloads the selected template from GitHub, uses its bundled copy if GitHub is unavailable, and updates the project name and package manager. Pass --install when you also want it to install dependencies.

Template dependencies are normal registry dependencies:

JSONpackage.json
1{2  "dependencies": {3    "svedocs": "latest"4  },5  "devDependencies": {6    "svedocs-cli": "latest"7  }8}

With --install, your chosen package manager installs these packages from its configured registry. No framework source is copied into the project.

Choose a template

Shell
1pnpm create svedocs my-docs --template minimal2pnpm create svedocs my-docs --template docs3pnpm create svedocs my-docs --template cloudflare

Template	Included routes	Best for
minimal	Docs shell and content routes.	Learning the basics or embedding docs into an existing app.
docs	Search, Ask AI fallback, sitemap, robots, and OG routes.	Most product documentation sites.
cloudflare	Everything in docs, plus Wrangler config and Cloudflare binding examples.	Cloudflare Pages and edge-first projects.

Remote template behavior can be controlled with environment variables:

Variable	Purpose
SVEDOCS_TEMPLATE_SOURCE=bundled	Force the CLI-bundled template copy.
SVEDOCS_TEMPLATE_SOURCE=github	Require GitHub and fail instead of falling back.
`SVEDOCS_TEMPLATE_REF=<branch	tag
SVEDOCS_TEMPLATE_REPOSITORY=<owner/repo>	Fetch templates from a different repository.

Add svedocs to an existing app

Install the framework and CLI:

Shell
1pnpm add svedocs2pnpm add -D svedocs-cli

Create svedocs.config.ts:

TypeScriptsvedocs.config.ts
1import { defineConfig } from 'svedocs/config';23export default defineConfig({4  site: {5    name: 'My docs',6    title: 'My docs',7    description: 'Documentation for my product',8    url: 'https://example.com'9  },10  content: {11    root: 'content',12    docs: 'content/docs',13    pages: 'content/pages'14  }15});

Register the Vite plugin:

TypeScriptvite.config.ts
1import { svedocs } from 'svedocs/vite';2import svedocsConfig from './svedocs.config';34export default {5  plugins: [6    svedocs({ config: svedocsConfig })7  ]8};

Import the default theme CSS once in the root layout:

Sveltesrc/routes/+layout.svelte
1<script>2  import 'svedocs/theme/styles.css';3</script>45<slot />

Then add the routes your site needs. A minimal setup can render DocsApp from svedocs/theme; the docs and cloudflare templates show the complete search, Ask AI, sitemap, robots, and OG setup.

Add content

Create the content roots and a first docs page:

Shell
1mkdir -p content/docs content/pages

Markdowncontent/docs/index.md
1---2title: Introduction3description: Start here to understand the product.4order: 15---67# Introduction89Welcome to the docs.

Verify the installation

Run these commands before adding hosted integrations:

Shell
1pnpm check2pnpm build

pnpm check validates the content manifest. pnpm build verifies that SvelteKit, the svedocs Vite plugin, route files, theme imports, and configured build mode all work together.

Upgrade svedocs

Generated projects include both svedocs and svedocs-cli. Upgrade them together:

Shell
1svedocs upgrade2svedocs upgrade 0.2.03svedocs upgrade 0.2.0 --no-install4svedocs upgrade --check-only

Before changing dependencies, the upgrade command checks whether the requested version crosses a known breaking release. There are no special migration rules yet; future releases can add them when needed.

Troubleshooting

Symptom	Check
The docs page renders without styles.	Confirm svedocs/theme/styles.css is imported from the root layout.
Routes do not update while editing content.	Confirm svedocs({ config }) is registered in vite.config.ts.
Search route works locally but not in production.	Confirm provider credentials or Cloudflare bindings exist in the runtime environment.
Build fails in spa mode.	Prefer edge or static; use spa only for constrained hosts that need a fallback.