【Svelte】怎样将 Docusaurus 网站部署到 Svelte 网站的子路径 /docs 下？

To host a Docusaurus site under the /docs path 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's static folder.

1. Configure Docusaurus

In your Docusaurus project, open docusaurus.config.js and update the baseUrl:

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

2. Build and Move

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

3. Handling Links in Svelte 5

When linking to your docs from your Svelte components, you must force a full page reload so SvelteKit's router doesn't try to handle the /docs route:

<script>
  // Svelte 5 component
</script>

<a href="/docs/" data-sveltekit-reload>View Documentation</a>

---

Method 2: Deployment Proxy (Best for Production/CI/CD)

If you are using a monorepo or don't want to manually copy files into the static folder, you should handle this at the hosting 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 have baseUrl: '/docs/' configured.

---

Method 3: Automated Build Script (Recommended)

If you want to keep them in one repository, you can automate the process in your package.json.

1. Structure:

   /my-monorepo
   ├── /svelte-app
   └── /documentation-site

2. In svelte-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:

1. Hydration Errors: If you don't use data-sveltekit-reload, SvelteKit will try to render the Docusaurus index.html inside your Svelte layout, which will fail or look broken.
2. Asset Paths: If baseUrl isn't set to /docs/ in Docusaurus, your CSS and JS files will look for /assets/js/... instead of /docs/assets/js/... and return 404s.
3. Trailing Slashes: Docusaurus prefers trailing slashes. Ensure your links are to /docs/ (with the slash) to avoid unnecessary redirects.

Which should you choose?

• Use Method 1 if you want one single deployment and the docs don't change very often.
• Use Method 2 if you want to deploy the docs independently of the main app (faster CI/CD).