Skip to content

fix(docs): unblock Pages build by excluding 5 workspace-only symlinks #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hoainho merged 2 commits into from
Jun 6, 2026
Merged

fix(docs): unblock Pages build by excluding 5 workspace-only symlinks #59

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a385cb4
Merge branch 'main' of https://github.com/hoainho/react-debugger-exte…
hoainho Jun 6, 2026
dfa90e8
fix(docs): unblock Pages build by excluding workspace symlinks from J…
hoainho Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/_config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Exclude workspace-only symlinks. They resolve on local dev (point to
# /Users/nhonh/Documents/personal/docs/) but break the Pages build on
# the CI runner. See PR #59 for the diagnosis and full context.
exclude:
- HARNESS.md
- HARNESS_BACKLOG.md
- FEATURE_INTAKE.md
- evidence
- templates
Comment on lines +4 to +9

@gemini-code-assist gemini-code-assist Bot Jun 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

While adding these paths to the exclude list in _config.yml seems like a logical fix, it unfortunately will not prevent the Jekyll build from failing on GitHub Pages.

Why this happens:

  1. Security Checks in Safe Mode: GitHub Pages runs Jekyll in safe mode. To prevent directory traversal vulnerabilities, Jekyll validates all symlinks in the source directory to ensure they do not resolve to paths outside the source directory.
  2. Realpath Resolution: To perform this validation, Jekyll (or its path resolution dependencies) calls File.realpath on every symlink it encounters during the initial directory scan.
  3. The Crash: Because these symlinks are broken on the CI runner, File.realpath throws Errno::ENOENT (No such file or directory @ rb_check_realpath_internal). This security check and directory scanning happen before the exclude rules are applied, meaning Jekyll will still crash with the exact same error.

Recommended Solution:

To preserve your local development workflow while unblocking the Pages build, you should delete these broken symlinks during the CI workflow before Jekyll runs.

Since the default GitHub Pages builder doesn't allow running custom commands, you can switch to a custom GitHub Actions workflow for deployment (which is now the standard recommendation by GitHub).

Here is an example of how you can structure the workflow step in .github/workflows/pages.yml to clean up the symlinks before building:

- name: Clean up workspace-only symlinks
  run: |
    rm -f docs/HARNESS.md docs/HARNESS_BACKLOG.md docs/FEATURE_INTAKE.md
    rm -rf docs/evidence docs/templates

This ensures the symlinks are tracked in Git for your local dev environment, but are safely removed on the CI runner before Jekyll scans the directory.

Loading