Merging the Template and Theme

Workflow for creating a custom SEFSC Theme for GitHub Pages Documentation Sites

Now that the template repo has been split apart and several new files added to the theme repo, the two repos need to be tied together in order for the website to work. This will be done using GitHub submodules for the reasons discussed earlier.

Step 8: Creating submodules

These steps take place in the template repo.

  1. Using a terminal or Command Prompt, navigate to the home directory of the template repo.

  2. Create a submodule for the navbar:

    git submodule add --branch navbars --force --name navbars_theme https://github.com/<GitHub-username>/<theme-repo> navbars

    where <GitHub-username> is the owner of the GitHub repository <theme-repo>.

  3. Create a submodule to import the theme itself:

    git submodule add --force --name documentation-theme-quarto https://github.com/<GitHub-username>/<theme-repo> theme

Steps 2 and 3 will create two new directories in the template repo: navbars and theme (the last argument in the command line calls).

  1. Commit the changes as usual, for example:

    git add .
git commit -m "Add navbar and theme files from theme repo"
git push origin docs

    On the template repo GitHub page, these new directories will show up with an appended commit ID (e.g., theme @ a1b2c3d). These commit IDs indicate the version of these two theme repo branches that are currently loaded into the template repo.

  2. In the .github/workflows directory, edit the `render-and-publish.yml’ file as follows:

    1. Change the push branch from main to docs:

      name: Render and deploy quarto files
on:
  push:
    branches: docs

    2. Append to the quarto-render-and-deploy checkout step as follows to checkout the submodules before rendering the project:

      jobs:
  quarto-render-and-deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

Step 9: Finish the metadata files

  1. In the template repo _quarto.yml:

    1. Append the directory theme/ to the theme.scss and theme-dark.scss files so that Quarto knows where to find them:

      format:
  html:
    theme:
      light: [cosmo, theme/theme.scss] 
      dark: [cosmo, theme/theme-dark.scss]

    2. Add the following block:

      metadata-files:
  - theme/_website.yml
  - navbars/_topnav_sefsc.yml
  - _metadata.yml

    Commit the changes.

  2. In the theme repo _website.yml, append the directory theme/ to the favicon call so that Quarto knows where to find it:

    website: 
  ...
  favicon: theme/images/favicon.png

    Commit the changes.

With everything committed to GitHub, the template repo’s external website (the URL from Step 1.8) should render properly.

Tip

The repo is configured to use GitHub Actions to automatically render and publish to the gh-pages branch whenever new changes are pushed to the main branch. It does, however, take a short period of time for the various processes to run behind the scenes, so updates may not appear immediately. On the GitHub repo homepage, a brown dot will appear next to username and latest commit message after a change is pushed, indicating that the page is being rebuilt. This dot will become a green check mark once successfully finished. The website can be refreshed once that happens.