Error when deploying to a fresh repo if there is a git sub-module in the repo

[damithc]

Steps:

1. Clone https://github.com/nus-cs2103/website-base and set up as follows:
   1. Run git submodule update --init --recursive to pull the content of the submodule.
   2. Switch to the cs2103 branch
2. Create an empty repo under your account
3. Push the local repo to that remote repo
4. Update site.json to point to your remote repo
5. Run markbind deploy

Expected: the website will be available through GitHub pages.
Actual: GitHub action fails to build and deploy the site. Here's an example run https://github.com/NUS-CS2103-AY2627-S1/website/actions/runs/29861657108/job/88739624473

The issue seems to affect when there is a sub-module (in our case, book). The gh-pages branch contains the submodule book@6bbfc2e instead of the book/ folder containing the pages of the sub-site.

Claude's explanation (the suggested fix worked):

---

The rendered textbook pages are missing from the deployed site. Because the index already contains a gitlink at book, git add . treats book/ as a submodule and refuses to add the rendered HTML that markbind build put in _site/book/. On last year's gh-pages, book is a real tree of rendered pages; on this year's it's just a pointer, so every /book/... URL on the live site 404s. (A related detail: _site/book/.git exists because the submodule's .git pointer file gets copied into the build — worth adding book/.git to the ignore list in site.json — but that file alone is harmless; the gitlink inherited at branch creation is what blocks the content.)

How to fix it
Don't just delete the remote gh-pages branch and redeploy — the orphan-creation path would inherit from master again and recreate the exact same problem. Instead, surgically remove the stray entries from the existing branch, using a temporary worktree so your main working tree is untouched:

git worktree add /tmp/ghp-fix gh-pages && cd /tmp/ghp-fix && git rm --cached book && git rm -q .gitmodules .gitignore && git commit -m "Remove source-branch leftovers from gh-pages" && git push cs2103-origin gh-pages && cd - && git worktree remove /tmp/ghp-fix
After that, the next markbind deploy will add the rendered book/** pages normally (with the gitlink gone from the index, the copied-in files just get added as regular files), and nothing reintroduces the submodule entry. Want me to go ahead and do that cleanup?

Likely cause: you're on Homebrew MarkBind 7.1.1 bundling gh-pages 6.3.0. If a prior semester used an older MarkBind whose bundled gh-pages handled the orphan checkout differently, that could shift the outcome too. But that's a local upgrade, still not the platform.

---

So, this could be related to a behaviour change of the gh-pages module used by MarkBind.

Not a big issue as I managed to deploy using the suggested workaround. It only affects sites with sub-modules and only at the initial deploy to a new remote repo.

Still, good to fix if there is a fix we can do on our side.