Using git submodules with GitHub Pages and Jekyll

[benfrancis]

Hi,

I have a website hosted on GitHub Pages and am trying to add a sub-folder for that site as a git submodule, which uses Jekyll to create a themed sub-site.

GitHub’s documentation says:

If the repository for your GitHub Pages site contains submodules, their contents will automatically be pulled in when your site is built.

This does seem to work and the Markdown content in my submodule gets rendered as HTML, but the _config.yml configuration file inside the submodule seems to be ignored and its jekyll theme is not applied.

Is there a way to get the jekyll configuration file inside the submodule to be used? Perhaps with a top level jekyll configuration file? If that is the solution then what happens if I have multiple sub-modules with different jekyll configurations?

Thanks

[otter-computer]

Hi @benfrancis, welcome to the GitHub Support Community!

Jekyll only supports a single root-level _config.yml file per site. This means that Pages won’t take into account the config file inside your submodule.

Can you give some more information on exactly why you want to use multiple? Are you importing a site from another repository in order to have it hosted on GitHub Pages too? If so, it may be simpler to just enable Pages on the repository you’re importing as a submodule instead.

[benfrancis]

Hi @thomasshaped, thanks for your response.

The top level site is a static HTML website which does not use Jekyll, but the /docs subdirectory (which is a separate repo included as a submodule) does. We previously used Netlify to deploy the site and its subdirectories but have moved back to GitHub Pages using submodules and would ideally like other submodules to use Jekyll as well (e.g. /blog).

Top level site repo: https://github.com/WebThingsIO/webthings.io
Docs submodule repo: https://github.com/WebThingsIO/docs

I tried adding a _config.yml file to the top level repository which pointed to /docs as a source and target for jekyll, but it didn’t work. Is there a way to make this work? Presumably from what you’ve said if it does work it will only work for a single subdirectory/submodule?

We are considering switching /docs from Jekyll to MkDocs so if we do that then supporting a single submodule for /blog might be enough.

Thanks

[otter-computer]

Thanks for explaining that, makes more sense to me what you’re doing now!

Pages will always only take into account a root-level _config.yml file. This means that any config files inside your submodule repositories will be ignored when they are imported, meaning that any specific themes you’ve chosen will be ignored.

If you’re switching to MKDocs then that should solve your problem just fine for this issue, but you may have to make certain considerations if you’re planning to use Jekyll again in future. For example, any Jekyll configuration will need to be made in the WebThingsIO/webthings.io repository, regardless if you’re using Jekyll for that direct site or not, as the root of that repository is the only place where Pages will look for a config file.

Another alternative would be to host separate Pages sites out of each of your repositories.

I notice that you’re using the webthings.io custom domain for this site. To keep your existing URLs the same you’ll need to rename your repository from WebThingsIO/webthings.io to WebThingsIO/webthingsio.github.io. Doing this will allow this custom domain to be inherited by all other Pages sites listed under your account instead of being hosted from a github.io address.

Once you’ve made that change you should then be able to go to any other repositories hosted under your GitHub account an enable Pages in their repository settings. Any repositories you do this with will be available at https://webthings.io/repository-name/. If you do this with your WebThingsIO/docs repository your site will then be hosted on Pages, with the correct Jekyll theme, at https://webthings.io/docs/.

If you’re unhappy changing the name of your WebThingsIO/webthings.io repository then you can still do this, though any existing domains will no longer work and Pages sites outside of this repository will be hosted from a github.io address (unless you add a different custom domain/subdomain to them in the repository settings).

You can choose to mix and match this approach—where some repositories are included as submodules and others are hosted as separate sites—but any Jekyll site will need to be hosted as a separate repository or will need to rely on the config file from the root repository.

[Edited to fix an incorrect repository name]

[benfrancis]

Fantastic, thanks! I totally forgot about the magic .github.io repo name and didn’t realise it would have that effect.

Marking this as solution but one slight edit, the repo name should be WebThingsIO/webthingsio.github.io not WebThingsIO/webthings.github.io

[otter-computer]

Oops, I missed that, sorry! You’re right, that is the correct repo name, it should use the org/account name 😅