Final Remarks

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

This page walked through the creation of two new GitHub repositories: a documentation skeleton template repository using Quarto, which can be duplicated and populated with headers and text to create document a model, source code, or any other project; and a second theme repository that contains the behind-the-scenes configurations, branding, etc. to control the look and functionality of the site. These two repositories were linked together using GitHub submodules allowing the theme repo to be managed separately from all documentation repos while ensuring that all documentation repos share the same look and feel. This is particularly important for adhering to organizational branding requirements.

Separating the website theme files from the content repository also minimizes the learning curve to creating a new site because there is no need to re-create or configure any back-end settings. This means there is no need to know or learn HTML, JavaScript, or any other languages used to generate the site itself. And by templating the Markdown files containing the actual content of the documentation site, next to no knowledge of Markdown is needed either: the user can essentially replace the placeholder text with the appropriate narrative. Instructions on how to proceed in creating a new repo using the template are contained in the HowTo pages. This template can also be easily added to an existing repo containing, for example, source code, allowing the documentation to live in a docs branch alongside the code itself in the main. Importantly, because all of this is done in GitHub, every component is completely version controlled.

We hope this page provides guidance for others within NOAA interested in creating their own Quarto website template. These can either be forked from NMNFS Open Science directly, as the steps describe, or from the SEFSC repos created herein. The latter may be particularly beneficial for other FMCs within NOAA Fisheries, as this SEFSC template may be closer to what such a user would want.