Customizing the Theme

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

Step 7: Customize the theme

These steps take place primarily in the theme repo created on the previous page but also reference (and modify) the template repo created earlier.

Quarto projects are configured using a _quarto.yml file; see the docs for more info. The new template repo contains this file already. The metadata sharing feature of Quarto allows that _quarto.yml file up to be split into multiple files. Quarto will combine them together again when the project is rendered. We will take advantage of this feature here.

GitHub Tip

Committing all changes at the end of each step below is strongly recommended, keeping in mind that some steps modify both the template and theme repos.

1. First, create a new file in the theme repo called _website.yml and populate it with any website configuration settings from the template repo _quarto.yml that should be consistent across all documentation pages. These settings include:

   • Website page navaigation
   • Repo actions
   • Format settings
   • Filter

   Delete the relevant lines from the template repo _quarto.yml and insert them into the theme repo _website.yml file.

   Caution

   For any section that gets split up, be sure to replicate the section header in the new yaml file so that Quarto knows how to merge them. See the example that follows.

   For example, the original template repo _quarto.yml file contains:

   website: 
     page-navigation: true
     title: "NOAA quarto simple" 
     site-url: "https://nmfs-opensci.github.io/NOAA-quarto-simple-python" 
     repo-url: "https://github.com/nmfs-opensci/NOAA-quarto-simple-python"
     repo-actions: [edit, source, issue]
     favicon: images/favicon.ico

   After completing this step, the new theme _website.yml file should contain:

   website: 
     page-navigation: true
     repo-actions: [edit, source, issue]
     favicon: images/favicon.ico

   leaving the following in _quarto.yml:

     website: 
       title: "NOAA quarto simple" 
       site-url: "https://nmfs-opensci.github.io/NOAA-quarto-simple-python" 
       repo-url: "https://github.com/nmfs-opensci/NOAA-quarto-simple-python"

   Note that both files contain a website: section header.

2. Take this a step further by creating a second file, _metadata.yml, in the theme repo to contain the only site information that a user will need to set when creating a new documentation site. For now, the four website elements above (title, site-url, and repo-url) are the only elements that need to be set for each project (this is the beauty of using Quarto for this application!) Remove this section from the template _quarto.yml file and insert them into the new theme repo _metadata.yml file.

   At this point, _quarto.yml should no longer contain a website section: it has been entirely distributed between _website.yml and _metadata.yml.

3. Back in the theme repo _website.yml file:

   1. Add and configure a page-footer to contain NOAA, Fisheries, and SEFSC contact information.
   2. Configure the sidebar with NOAA and SEFSC information.
   Note

   Setting contents: auto allows the sidebar to be automatically generated, eliminating the need for manual construction or configuration. Users should therefore follow the instructions in the docs for facilitating this feature.

4. In the theme repo theme.scss and theme-dark.scss files:

   1. Assign NOAA-specific colors to variable names for easy use later. These colors were taken from the NOAA Fisheries Brand Standards and include NOAA primary colors, grays, and secondary colors for each region. For example:

      // NOAA Fisheries Primary Palette
      $noaa-light-blue: #0093D0;
      $noaa-dark-blue: #0055A4;
      $navy-blue-pantone: #00467F;

   2. Set font colors:

      // Font colors
      $headings-color: $navy-blue-pantone !default;
      $link-color: #216f9b !default;

5. Upload a new favicon image to the images directory, if desired. If a different file name is used, modify _website.yml accordingly:

   website:
     ...
     favicon: path/to/new-favicon.ico

6. Create a new branch on the theme repo called navbars to be used for the top navigation bar of the documentation site.

   Command line:

   git -b checkout navbars

   Or on the repo’s GitHub website (be sure to run git fetch locally to retreive it)

7. Create a new file on this branch, _topnav_sefsc.yml.

8. Add and configure a navbar for the website containing relevant resources and links. For example:

   website:
   navbar:
      background: $navy-blue-pantone
      search: true
      right:
        - text: "SEFSC Resources"
          menu:
            - href: https://www.fisheries.noaa.gov/contact/southeast-fisheries-science-center
              text: SEFSC Homepage
            - href: https://nmfs-opensci.github.io/
              text: NOAA Fisheries Open Science
        - text: "Software & Documentation"
          menu:
            - href: https://github.com/sefsc
              text: SEFSC GitHub Organization
            - href: https://noaa-fisheries-integrated-toolbox.github.io/
              text: NOAA Fisheries Integrated Toolbox

   Commit the changes to this branch, for example:

   git add .
   git commit -m "Initial commit"
   git push origin navbars

Next we will tie all of this together.