How to add submodule into gh-pages branch & build static pages correctly?

Question

I have several project pages to maintain, and all of them use a same theme (I packaged it into a separate repo which called KYProjectPageTheme).

Just copy the KYProjectPageTheme's entire folder to gh-pages branch's root dir & then push it to Github works very well. I'll receive a notification when static pages build successfully.

However, I want to add KYProjectPageTheme as a submodule under gh-pages branch. This works well in my local machine. But when I pushed it to Github, I could not receive the notification anymore! And static pages are still in the previous state, i.e. modification after I've added a submodule did not affect.

What I guess is that Github's static page generator will not work when there's a submodule in gh-pages branch. But actually, I don't need a generator to generate static pages, I just need to modify pages in HTML & push it to gh-pages. Why not my index.html updated?

Any idea? Is there some workarounds to solve this issue?

Thanks in advance!

Answer 1

I've got the answer from the Github (thanks @Robert).

Using submodules with Pages

If your repository contains submodules, they will automatically be pulled in when the Page is built.

Make sure you use the https:// read-only URL for your submodules, including nested submodules. You can make this change in your .gitmodules file.

Submodules must also be served from public repositories, as the Pages server cannot access private repositories.

So, I need to use

https://github.com/Kjuly/KYProjectPageTheme.git (new page recommends to use "https://")
git://github.com/Kjuly/KYProjectPageTheme.git (old page recommends to use "git://")

instead of

git@github.com:Kjuly/KYProjectPageTheme.git

And it works perfect now!!

---

Note, Old page said:

HTTPS and SSH URLs will cause the build to fail with a "submodule fetch failed" error.

Not sure whether the HTTPS one works or not now, but if the https:// not works for you, just keep using git:// instead.

Answer 2

I frequently run into this when I use SSH for my main repository and HTTPS for my sub-repository (prototyping framework).

I never tracked down exactly why this happens. I even contacted GitHub staff once, and they had to fix something in my repository.

It turns out there's an easier way: Use HTTPS for the parent repository and all subrepositories. This seems to work without any other tweaking.

Answer 3

I was generating a static website with Hugo, and had to format my .gitmodules file like so:

[submodule "themes/code-editor"]
    path = themes/code-editor
    url = https://github.com/aubm/hugo-code-editor-theme.git