Merged
Conversation
From the GitHub Actions logs, identified two remaining issues: 1. var baseUrl = "/" was not being changed - Original HTML: var baseUrl = "/" - Fixed HTML: var baseUrl = "/" (unchanged!) - Problem: sed pattern was missing for this case 2. theme-settings.json loading from wrong path - Error: 404 on https://soundblaster.github.io/theme-settings.json - Should be: /NavigationSplitView/theme-settings.json Changes: - Added sed patterns for var baseUrl and const baseUrl in HTML files - Added specific fix for /theme-settings.json in JavaScript - Added general pattern to fix all root-level .json files Now the workflow fixes: - HTML: var baseUrl, script src, link href, favicons - JS: theme-settings.json, other .json files, /data/, /documentation/, /tutorials/ This should be the final piece needed for DocC to work on GitHub Pages.
Following the pattern from SpecificationKit repository, added: 1. .nojekyll file - Prevents GitHub Pages from ignoring files/directories starting with _ - DocC generates files like _static/ that need to be served 2. Root redirect to documentation page - DocC documentation lives at /documentation/<bundle-id>/ - Not at the root path - Created a clean redirect page that automatically redirects users - Uses both meta refresh and JavaScript for compatibility Without this: - Users opening https://soundblaster.github.io/NavigationSplitView/ - See "page not found" because no content at root With this: - Users are automatically redirected to: https://soundblaster.github.io/NavigationSplitView/documentation/navigationsplitview/ - Where the actual documentation lives This matches the standard DocC deployment pattern used in the SpecificationKit repository.
This is a much cleaner solution than post-processing with sed. Changes to Xcode project: - Added DOCC_HOSTING_BASE_PATH = NavigationSplitView to project settings - Applied to both Debug and Release configurations - This tells DocC to generate correct paths from the start Changes to GitHub Actions workflow: - Removed all sed hacks for path fixing - DocC now generates correct paths natively because of the Xcode setting - Kept .nojekyll and root redirect (these are still needed) - Much simpler and more maintainable How it works: 1. Xcode setting tells docc to use /NavigationSplitView/ as base path 2. docc convert generates .doccarchive with this setting baked in 3. docc process-archive respects this and generates correct HTML/JS 4. No post-processing needed! This follows the official Apple recommendation for DocC on GitHub Pages: https://www.moritz.wiki/en/blog/docc-github-pages-xcode-configuration Benefits: - Cleaner workflow (60+ lines of sed removed) - More reliable (uses native DocC feature) - Easier to maintain - Works the way Apple intended
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
51
to
+77
| - name: Prepare static documentation output | ||
| run: | | ||
| set -eo pipefail | ||
| # The DOCC_HOSTING_BASE_PATH is now set in Xcode project settings | ||
| # so DocC will generate the correct paths automatically | ||
| xcrun docc process-archive transform-for-static-hosting DocsArchive/NavigationSplitView.doccarchive \ | ||
| --hosting-base-path "$DOCC_HOSTING_BASE_PATH" \ | ||
| --output-path DocsBuild | ||
|
|
||
| # Debug: Show the structure of generated files | ||
| echo "=== Generated file structure ===" | ||
| find DocsBuild -type f | head -20 | ||
|
|
||
| # Debug: Show original index.html | ||
| echo "=== Original index.html (first 30 lines) ===" | ||
| head -30 DocsBuild/index.html || true | ||
|
|
||
| # Fix resource paths in HTML files | ||
| # DocC's --hosting-base-path doesn't add the base path to script/link tags in HTML | ||
| echo "=== Fixing resource paths in HTML files ===" | ||
| find DocsBuild -type f -name "*.html" | while read -r file; do | ||
| # Fix script src attributes | ||
| sed -i '' 's|src="/js/|src="/'$DOCC_HOSTING_BASE_PATH'/js/|g' "$file" | ||
| sed -i '' 's|src="/css/|src="/'$DOCC_HOSTING_BASE_PATH'/css/|g' "$file" | ||
| sed -i '' 's|src="/images/|src="/'$DOCC_HOSTING_BASE_PATH'/images/|g' "$file" | ||
|
|
||
| # Fix link href attributes | ||
| sed -i '' 's|href="/js/|href="/'$DOCC_HOSTING_BASE_PATH'/js/|g' "$file" | ||
| sed -i '' 's|href="/css/|href="/'$DOCC_HOSTING_BASE_PATH'/css/|g' "$file" | ||
| sed -i '' 's|href="/images/|href="/'$DOCC_HOSTING_BASE_PATH'/images/|g' "$file" | ||
|
|
||
| # Fix favicon paths | ||
| sed -i '' 's|href="/favicon.ico"|href="/'$DOCC_HOSTING_BASE_PATH'/favicon.ico"|g' "$file" | ||
| sed -i '' 's|href="/favicon.svg"|href="/'$DOCC_HOSTING_BASE_PATH'/favicon.svg"|g' "$file" | ||
| done | ||
|
|
||
| # Fix data and documentation paths in JavaScript files | ||
| # JavaScript code has hardcoded absolute paths that need the base path prefix | ||
| echo "=== Fixing paths in JavaScript files ===" | ||
| find DocsBuild -type f -name "*.js" | while read -r file; do | ||
| # Fix data directory paths | ||
| sed -i '' 's|"/data/|"/'$DOCC_HOSTING_BASE_PATH'/data/|g' "$file" | ||
| sed -i '' "s|'/data/|'/$DOCC_HOSTING_BASE_PATH/data/|g" "$file" | ||
|
|
||
| # Fix documentation paths | ||
| sed -i '' 's|"/documentation/|"/'$DOCC_HOSTING_BASE_PATH'/documentation/|g' "$file" | ||
| sed -i '' "s|'/documentation/|'/$DOCC_HOSTING_BASE_PATH/documentation/|g" "$file" | ||
|
|
||
| # Fix tutorials paths | ||
| sed -i '' 's|"/tutorials/|"/'$DOCC_HOSTING_BASE_PATH'/tutorials/|g' "$file" | ||
| sed -i '' "s|'/tutorials/|'/$DOCC_HOSTING_BASE_PATH/tutorials/|g" "$file" | ||
| done | ||
|
|
||
| # Debug: Show fixed index.html | ||
| echo "=== Fixed index.html ===" | ||
| cat DocsBuild/index.html || true | ||
|
|
||
| echo "" | ||
| echo "=== Checking for NavigationSplitView in JS files ===" | ||
| grep -o "NavigationSplitView" DocsBuild/js/*.js | head -5 || echo "Not found" | ||
| echo "=== Documentation processed for static hosting ===" | ||
| echo "Hosting base path: $DOCC_HOSTING_BASE_PATH" | ||
|
|
||
| - name: Add .nojekyll and root redirect | ||
| run: | | ||
| # Add .nojekyll to prevent GitHub Pages from ignoring files starting with _ | ||
| touch DocsBuild/.nojekyll | ||
|
|
||
| # Create redirect from root to documentation page | ||
| # The actual documentation lives at /documentation/<bundle-id>/ | ||
| cat > DocsBuild/index.html << 'EOF' | ||
| <!DOCTYPE html> | ||
| <html lang="en-US"> | ||
| <head> | ||
| <meta charset="utf-8"> | ||
| <title>Redirecting to NavigationSplitView Documentation</title> | ||
| <meta http-equiv="refresh" content="0; url=./documentation/navigationsplitview/"> | ||
| <link rel="canonical" href="./documentation/navigationsplitview/"> |
There was a problem hiding this comment.
The new workflow assumes that setting DOCC_HOSTING_BASE_PATH in the Xcode project makes DocC emit asset URLs that include the repository path, so the sed-based post‑processing was deleted. However, the build still invokes xcrun docc convert directly rather than xcodebuild, so the project build setting is never read and DocC continues to output absolute /js, /css, /data, /documentation, and /tutorials URLs. When the site is published under /NavigationSplitView on GitHub Pages those URLs 404, leaving the documentation without styles or scripts. The removed rewriting step was the only thing adjusting those paths. Consider keeping the rewrite or switching to an invocation that actually applies the Xcode build setting.
Useful? React with 👍 / 👎.
SoundBlaster
deleted the
claude/fix-docc-github-pages-urls-011CV2q14oULMheEHTbHVHsq
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Use "DocC Archive Hosting Base Path" in Xcode Project
Source: https://www.createwithswift.com/configuring-the-hosting-base-path-in-xcode-to-publish-docc-documenation-on-github-pages/