Creating the Custom Theme

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

IOOS uses a custom website theme to maintain consistent formatting, appearance, and functionality across all documentation sites. Some of the most noticable thematic features include:

IOOS header logo added and colors changed in accordance with branding guidelines
Page footer with appropriate links and contact information
Common horizontal navigation bar with IOOS-related links and resources
“Behind the scenes” configurations that govern how the website works

This theme is simply a GitHub repository containing the necessary configuration files, scripts, and visual branding to provide the underlying structure of a documentation web page. IOOS implements this theme in all documentation pages through the use of GitHub submodules, the details of which are beyond the scope of this document but, in short, allow theme files to be contained in their own repository and then embedded into a separate repository that contains the content files for the web page. There are several advantages to this. First, it means that individuals seeking to write documentation do not need to worry about creating a website. The “guts” already exist. Second, the same theme repository can be embedded into an infinite number of documentation repositories, providing a consistent look and feel across all of them. Finally, the theme can be modified at any time by the owner (for example, the IOOS Program Office) and those changes can easily be propagated through to every other site that uses the theme by simply pulling the changes into each of the respective repositories.

Step 4: Create a new “documentation-theme-quarto” repository

This is done on the GitHub website and assumes the user already has a GitHub account and is signed in. These steps will duplicate the NOAA Open Science repo into that user’s account. This repo will contain the theme files and manage site appearances according to the needs of the SEFSC.

On the “Repositories” tab, click the green “New” button to create a new repo.
Do not select a template. Select a repository ower, provide a name (e.g., “documentation-theme-quarto”), and type a description, if desired.
Click “Create repository”. We will refer to this repo as the theme repo throughout these instructions.

Step 5: Clone this repository locally

One the main page of the new repo, click the green “< > Code” button.
Copy the HTTPS web URL shown in the popup.
On your local computer, in a terminal window or Command Prompt, navigate to where the theme repo is to be downloaded, and type
```
git clone <URL>
```
where <URL> is the web URL from Step 4.2 above.

Important

This theme repo can be located in the same parent directory as the template repo created earlier, but it should not be located within that repo.
Press enter. The repo will now be downloaded to your local machine.

Alternatively, after Step 4.1, either use the “Open with GitHub Desktop” or the “Download ZIP” options shown above to download the repo. Be sure to unzip it if you retrieve it this way.

Step 6: Populate the theme repository

Move the following from the template repo to this new theme repo:
- theme-dark.scss
- theme.scss
- LICENSE
- images (directory and content)
If using a terminal or Command Prompt (Git Bash is recommended on Windows):

mv -r path/to/template-repo/filename path/to/theme-repo

If you are in the template repo directory, you can use:

mv filename path/to/theme-repo

Or, if you are in the theme repo directory:

mv -r path/to/template-repo .
Commit these changes to each repo. You can use the same commit message for each if you want, for example:
```
git add *
git commit -m "Move theme files from template repo to theme repo"
git push origin main
```
Note

This will have to be done separately in each repo.

Now we have a theme repo, we can customize it for the SEFSC.