To host a Docusaurus site under the/docspath of a Svelte 5 (SvelteKit) project, you have two primary ways to do it.

Method 1: The “Static” Approach (Simplest)

This method involves building your Docusaurus site and placing the output inside SvelteKit’sstaticfolder.

1. Configure Docusaurus

In your Docusaurus project, opendocusaurus.config.jsand update thebaseUrl:

// docusaurus.config.jsexportdefault{title:'My Docs',url:'https://your-domain.com',baseUrl:'/docs/',// CRITICAL: This must match your folder nametrailingSlash:true,// ... rest of config};

2. Build and Move

1. Build your Docusaurus site:npm run build.
2. This creates abuildfolder.
3. In your Svelte 5 project, create a folder:static/docs/.
4. Copy everything from the Docusaurusbuildfolder into your Svelte project’sstatic/docs/folder.

3. Handling Links in Svelte 5

When linking to your docs from your Svelte components, youmustforce a full page reload so SvelteKit’s router doesn’t try to handle the/docsroute:

<script> // Svelte 5 component </script> <a href="/docs/">Method 2: Deployment Proxy (Best for Production/CI/CD)
If you are using a monorepo or don’t want to manually copy files into thestaticfolder, you should handle this at thehosting level(e.g., Vercel, Netlify, or Nginx).
For Vercel (vercel.json):
If you have two separate projects (one for Svelte, one for Docusaurus), you can use “Rewrites” in your Svelte project’s root:
{"rewrites":[{"source":"/docs/:path*","destination":"https://your-docusaurus-site.vercel.app/docs/:path*"}]}
Note: Docusaurus must still havebaseUrl: '/docs/'configured.
Method 3: Automated Build Script (Recommended)
If you want to keep them in one repository, you can automate the process in yourpackage.json.
Structure:
/my-monorepo ├── /svelte-app └── /documentation-site
Insvelte-app/package.json, create a build script:
{"scripts":{"build:docs":"cd ../documentation-site && npm run build","copy:docs":"cp -r ../documentation-site/build/* ./static/docs/","build":"npm run build:docs && npm run copy:docs && vite build"}}
Critical Issues to Watch For:
Hydration Errors:If you don’t usedata-sveltekit-reload, SvelteKit will try to render the Docusaurusindex.htmlinside your Svelte layout, which will fail or look broken.
Asset Paths:IfbaseUrlisn’t set to/docs/in Docusaurus, your CSS and JS files will look for/assets/js/...instead of/docs/assets/js/...and return 404s.
Trailing Slashes:Docusaurus prefers trailing slashes. Ensure your links are to/docs/(with the slash) to avoid unnecessary redirects.
Which should you choose?
UseMethod 1if you want one single deployment and the docs don’t change very often.
UseMethod 2if you want to deploy the docs independently of the main app (faster CI/CD).