如何无需Apache服务器及.htaccess配置运行Xcode DocC并部署为静态站点？

Great question! You absolutely can host your DocC archive as a static site on platforms like GitHub Pages, Netlify, or Cloudflare Pages—no Apache server or system-level changes (like modifying /etc/hosts) required. The core issue with opening the .doccarchive/index.html file directly is that DocC's web app is a single-page application (SPA) relying on client-side routing. Browsers restrict path resolution for local files, and without server-side URL rewriting, direct requests to subpaths (like /documentation/your-framework) fail to load the correct content.

Here's the step-by-step solution to get your DocC docs hosted as a static site:

1. Build the DocC Archive for Static Hosting #

Use the docc command-line tool (or Xcode's xcodebuild) with specific flags to generate a static-hosting-friendly version of your docs. These flags ensure the correct base path is set and the file structure is optimized for static servers:

Using docc directly: #

docc convert Sources/YourFramework/YourFramework.docc \
    --output-path ./docs \
    --hosting-base-path /documentation/ \
    --transform-for-static-hosting

• Replace /documentation/ with your actual base path (e.g., if your docs live at the root of your site, use / instead).
• The --transform-for-static-hosting flag adjusts the archive to work with static site routing rules.

Using Xcode's xcodebuild: #

xcodebuild docbuild \
    -scheme YourFrameworkScheme \
    -destination 'generic/platform=iOS' \
    OTHER_DOCC_FLAGS="--hosting-base-path /documentation/ --transform-for-static-hosting" \
    BUILD_DIR=./build

After running this, your optimized docs will be in the build output directory (usually under build/Documentation/).

2. Configure Routing for Your Static Host #

Since DocC is an SPA, you need to tell your hosting platform to redirect all non-static resource requests to index.html so the client-side router can handle them. Here's how to set this up for popular platforms:

• Netlify: Create a _redirects file in your docs root directory with this line:

  /*    /index.html   200
  

  This rule sends every request (except for static assets like CSS/JS/images) to index.html.

• Cloudflare Pages: Add a _config.yaml file to your docs root with these routes:

  routes:
    - source: "/*"
      destination: "/index.html"
    - source: "/assets/*"
      destination: "/assets/:splat"
  

  Alternatively, you can set up these rules directly in the Cloudflare Pages dashboard under "Routing".

• GitHub Pages: GitHub Pages doesn't natively support SPA routing, but you can work around this by:

  1. Copying index.html to create a 404.html file in your docs root.
  2. The --transform-for-static-hosting flag will automatically add the necessary route normalization logic to handle this setup.

3. Upload to Your Static Hosting Platform #

Simply upload the generated docs directory to your chosen platform (e.g., push to a GitHub repo for GitHub Pages, drag-and-drop to Netlify, or connect your repo to Cloudflare Pages). No additional server setup is needed—your docs will load correctly as a fully static site.

As you've already tested with Netlify, this approach works seamlessly for hosting DocC docs without relying on Apache or custom system configurations.

内容的提问来源于stack exchange，提问作者Ben Butterworth