Updating the Theme

Syncing website theme and navbar with other SEFSC documentation pages

The SEFSC-documentation-quarto-skeleton repository uses the SEFSC documentation-theme-quarto repo to ensure consistent documentation format and functionality. This is accomplished using GitHub submodules as described in Merging the Template and Theme. When modifications are made by the SEFSC documentation-theme-quarto repo managers, the changes need to be manually pulled into each repo linking to it. Periodically checking for updates upstream will ensure consistency across all SEFSC documentation pages.

The theme and navbars directories are both imported as submodules. Neither directory should be ever be manually modified within any cloned or forked documentation rep. Doing so would defeat the purpose of using submodules.

Tip

One way to know that theme and navbars are submodules is to look at the contents of the docs branch on the repo’s webpage (for example, here.) Notice the icon for these two folders contain an arrow and the directory names are followed by an “@” and seven characters (e.g., theme @ eea3d56). The icon arrow can be interpretted as pointing to another external repository and the @ eea3d56 indicates the specific commit of that repository that is being read in. Any upstream updates to the theme repo will result in a new commit code, but downsteam submodules need to be manually updated to retrieve the new commits.

Updating the submodules

All of the following is done locally using a command line terminal.

Change directories (cd) into the local repo’s parent directory. This is the directory that contains the theme and navbars folders. Change to the docs branch if needed. Check for any uncommitted changes on the branch and commit them now (not necessarily required but strongly recommended.)

cd sefsc-documentation-quarto-skeleton
git checkout docs
git status

Pull the updates from the remote submodule repos:

git submodule update --init --force --remote

This will check both submodules and should print its status to the page. In the example below, the theme directory has been updated.

As noted in Merging the Template and Theme, the theme directory is linked to the main branch of the template repo. GitHub sees the new commit and returns both the existing commit and the new one (eea3d56..84d91cd main -> origin/main).

Checking the status of the repo again will reveal that new commits were made to theme and also displays the message associated with the latest commit.

Commit and push these changes as usual.

git add theme
git commit -m "Update theme"
git push origin docs

Tip

It may be beneficial to use the same commit message here as was associated with the theme repo update. If the commit message is descriptive (and hopefully it is), this will keep track of what actually changed – which is the point of commit messages in the first place. Thus, in this example:

git add theme
git commit -m "Change repo branch to docs and url behavior to new tab"
git push origin docs

It should now be updated and good to go. Verify the new commit code shows up in the repo file list on the landing page. The new changes will take affect once the gh-pages site finishes rendering.

How often should submodules be updated?

Theme files should not change often, but unfortunately, when they do, there is currently no automatic way for forked or cloned repos downstream to know. Users are encouraged to check for changes using the git submodule update --init --force --remote command whenever they make modifications to their documentation site and, ideally, on some regular cadance, minimally once a year. If there are no new changes, this command will simply indicate that the submodules “checked out” with the latest commit code and no further action is needed.