About This Project

A technical overview of customizing the theme, creating the skeleton template, and merging the two together

Quarto is used widely across NOAA Fisheries because of its flexibility, alignment with open science principles, integration with the R programming language and RStudio, and its relative ease of use. A number of use cases, including several webpages, are demonstrated on the NMFS Open Science GitHub page. While most NOAA Fisheries staff use Quarto with R and RStudio, Quarto also supports Python, Jupyter, and Visual Studio (VS) Code, all of which are more common within the computer science and, in particular, the artifiicial intelligence and machine learning communities. One of the most compelling features of Quarto is its seamless integration with GitHub for version control and hosting websites.

The decision to use GitHub Pages (gh-pages) for SEFSC documentation was inspired by its widespread use within IOOS. Correspondence with an IOOS data management analyst revealed that all IOOS documentation pages are either already utilizing gh-pages or are in the process of migrating to it because of the strengths listed in Table 1. IOOS hosts a Documentation Portal within their organizational GitHub account to compile all products and projects documentation in one central location.

An existing NMFS Open Science template for a simple Quarto web book with Python support provided the starting point (see the repository’s acknowledgements for full credit.) This repository (repo) contains both website configuration files, such as yaml files and images, and content files in the form of Quarto Markdown files. It was pre-configured to build and deploy the web book (i.e., webpage) to a gh-pages branch while the configuration and content files resided in the main branch. More on this later. The steps taken to replicate and adapt this for SEFSC documentation pages follow.