Migrating to svocs
Move a Fumadocs, Nextra, Docusaurus, Starlight, MkDocs, mdBook or Obsidian site to svocs: run the migration, port what it can't convert, fix dead links, and deploy.
Moving an existing docs site to svocs has two parts. svocs migrate converts the content in about a minute. The parts of the old site that were code, such as custom components, the header and the landing page, you port by hand. For a site of around a hundred pages, plan on an afternoon.
Your source site is never modified, so you can stop at any step and nothing is lost.
Before you start
- Node.js 22.17 or newer. The generated site requires it.
- Bun. The commands on this page use it.
- The source site checked out on your machine, for example with
git clone.
1. Run the migration
npx svocs-cli@latest migrate ../old-docs ../new-docs \
--site-name="My Project" \
--site-url=https://docs.example.com \
--repo-url=https://github.com/me/docs \
--accent=#3b82f6The first path is the source site. The second is a new or empty folder for the svocs site. Keep @latest: without it, npx can run an older copy it cached earlier.
The flags are optional:
--site-name: the name in the header and page titles. Defaults to a name read from the source site’s config orpackage.json.--site-url: the production URL, used for the sitemap, social cards andllms.txt. Include the sub-path if the site has one.--repo-url: the header’s GitHub button and the “Edit on GitHub” links.--repo-branch: the branch “Edit on GitHub” links point at. Defaults tomain.--accent: the theme color.--search: the search backend. Defaults to Pagefind. See Search.
You can change the name, URLs and branch later in src/lib/site.ts, and the accent in src/routes/+layout.svelte.
2. Read the report
The migration ends with a report. It has four kinds of lines:
- Converted pages: how many pages became
.mdand.svxfiles, and how many_meta.jsonfiles carry the sidebar order. - TODO lines: pages with blocks the converter could not map. Step 3 covers these.
- Notes: things it mapped but wants you to check, such as card lists, copied static files, or icons with no svocs equivalent.
- Dead links: links to pages that do not exist. Most were already broken on the old site. Step 5 covers these.
CLI lists what each source framework’s syntax becomes.
3. Port the TODO blocks
Search the new site for svocs migrate TODO. Each match is a block the converter commented out instead of guessing, so the site still builds. Common cases:
| Source block | What to do |
|---|---|
A custom component, such as <ResourceLinks repo="x" /> | Rewrite it as a Svelte component. See Your own components. |
Raw JSX with style={{…}} or className= | Rewrite it as plain HTML with style="…" and class="…". |
An mdBook {{#include}} | Use an <include> for a Markdown page. Paste anything else in. |
Your own components
Components from React-based sites (Fumadocs, Nextra, Docusaurus) need a rewrite in Svelte. That is usually short: props come from $props(), className becomes class, and {cond && <X />} becomes {#if cond}<X />{/if}.
Put your components in a folder of your own, such as src/lib/my-site/. svocs update only writes files that come from the svocs template, so it never touches that folder. Then import them in any .svx page:
<script>
import ResourceLinks from '#lib/my-site/ResourceLinks.svelte';
</script>
<ResourceLinks repo="my-repo" />A page that uses a component must be a .svx file. Rename it from .md to .svx. Its URL does not change.
Reusing a page inside another page
Import another content page and render it like a component. svocs adds its headings to the host page’s table of contents, and its text to search and llms.txt:
<script>
import EntityMethods from './entity-methods.svx';
</script>
<EntityMethods />If the shared page should not appear in the sidebar on its own, set "hidden": true on it in _meta.json. See Navigation.
A Fumadocs include of one section, such as <include>ped.mdx#methods</include>, stays an <include> of that section. See Reusing content. One difference: when the id is a heading, Fumadocs stops at the next heading of any level, and svocs stops at the next heading at the same level or higher. Check pages that include a heading with subheadings under it.
4. Port the site around the content
The converter only reads the content folder. Everything else on the old site was code, so it does not carry over:
| Part of the old site | Where it goes in svocs |
|---|---|
| Header links | Add <a> elements to the links snippet in src/routes/+layout.svelte. See Navigation. |
| Footer | The footer snippet in src/routes/+layout.svelte. |
| Landing page | src/routes/+page.svelte. |
| Favicon | Copy it into static/, then set the <link rel="icon"> in src/app.html. |
| Colors and fonts | See Theming. |
| Analytics scripts | Add them to <head> in src/app.html. |
For Fumadocs, Nextra, Starlight and Docusaurus sites, files in the source’s public/ (or Docusaurus static/) folder are already copied into static/. Next.js apps often keep the favicon in app/ instead, so check there too.
5. Fix dead links, then make the build strict
- Run
bun install, thenbun run build. The build prints a warning for each link to a missing page and each link to a missing#anchor. This includes links the report could not check, such as/guideon a site whose docs lived under/docs. - Fix each link in
content/. - In
vite.config.ts, delete theprerender: { handleHttpError: 'warn', handleMissingId: 'warn' }line and the comment above it.
From then on, a broken link fails the build instead of shipping. See Troubleshooting.
6. Preview
bun run devThen open http://localhost:5173/docs. To check the exact files you will deploy, run bun run build, then bun run preview.
7. Deploy
Follow Cloudflare Pages or GitHub Pages. If the old site used a custom domain on GitHub Pages, read Custom domain first: the default workflow builds for a sub-path.
“Edit on GitHub” links point at content/<page> in the repository from --repo-url. They work once the new site sits at the root of that repository, for example after a pull request that replaces the old site’s files with the new ones.