SVOCS

SVOCS is a markdown-first documentation site generator built on SvelteKit and Svelte 5. Write markdown in content/, drop in Svelte components where you need them, and ship a fully static site. No server required.

Docs and live demo: svocs.dev (the site is built with SVOCS itself).

bunx create-svocs-docs@latest my-docs
# or: pnpm create svocs-docs my-docs
# or: npm create svocs-docs@latest my-docs
# or: deno run -A npm:create-svocs-docs my-docs
cd my-docs && bun install && bun run dev

The scaffolder asks for your site name, production URL, repository link, accent color, search backend, and deploy target. It can also generate baseline content from an existing GitHub repo, heuristically for free or with an LLM using your own API key.

• Markdown-first content — every file under content/ becomes a route; .svx files mix Svelte components into markdown via mdsvex
• Built-in component library — Callout, Tabs, Steps, Cards (with an auto-populating mode for section landing pages), Collapse, Bleed, Banner, FileTree, ImageZoom
• Page icons — a curated hand-drawn icon set, set per page or per section, shown in the sidebar and page title
• Search, five ways — Pagefind by default (zero config, no server), or Orama, FlexSearch, Typesense, Chroma, all behind one ⌘K dialog
• Social preview cards — a 1200×630 OG image per page, rendered at build time by Takumi with no headless browser
• Math and diagrams — LaTeX via KaTeX, diagrams via Mermaid
• AI-ready output — llms.txt and llms-full.txt endpoints, plus a sitemap
• Obsidian-compatible — open content/ as a vault; [[wikilinks]], ![[embeds]], > [!tip] callouts, highlights, comments, and publish: false drafts build as-is, and npx svocs-cli migrate imports an existing vault
• Theming — one accent color drives the whole palette (dark and light), with a View Transitions dissolve on theme switch
• Site maintenance — npx svocs-cli doctor checks configuration; npx svocs-cli update applies template fixes to files you haven't modified; npx svocs-cli sync refreshes pages that mirror a README, a GitHub file, or a repo analysis; a scheduled workflow opens the resulting PR weekly
• Migration — npx svocs-cli migrate converts an existing Fumadocs, Nextra, Docusaurus, Starlight, MkDocs, or mdBook site, or an Obsidian vault, mapping components and flagging what needs a human — these are all tools we respect, svocs is just one more option
• Static output — deploys to Cloudflare Pages, GitHub Pages, or any static host; BASE_PATH support for sub-path hosting

This repository is also the source of svocs.dev itself — content/, src/, and scripts/ at the root are the documentation site.

bun install
bun run dev          # dev server at localhost:5173
bun run check        # svelte-check
bun run lint         # prettier + eslint
bun run test:unit    # vitest
bun run build        # static build into build/, incl. search index + OG cards
bun run preview

Bun is the primary package manager; pnpm (pnpm <script>) and Deno (deno task <task>, see deno.json) are also supported.

Known quirk: mdsvex emits Svelte 5 deprecation warnings for context="module" in generated markdown modules. They don't block builds.

The build output in build/ is fully static. Step-by-step guides: Cloudflare Pages and GitHub Pages. For sub-path hosts such as GitHub Pages project sites:

BASE_PATH=/my-repo bun run build

SVOCS leans on a lot of open-source work:

• Svelte & SvelteKit — the framework underneath everything
• Takumi by Kane — the Rust renderer behind our OG cards; it's the reason builds don't need headless Chromium
• mdsvex — markdown preprocessing with Svelte components
• Pagefind, Orama, FlexSearch, Typesense, and Chroma — the search backends
• KaTeX and Mermaid — math and diagram rendering
• Clack — the scaffolder's interactive prompts
• Satoshi by the Indian Type Foundry — the typeface, self-hosted via Fontshare's free license

MIT