Customization

Creating your own documentation page using the SEFSC Quarto Theme

Step 2: Setting up your site for editing

Editing content in your new fork of the documentation skeleton repository can be done in one of two ways: 1. Locally using a code editor and a Quarto installation, or 2. Online using the GitHub website

This repo includes a GitHub Action that will render (build) the website automatically when you make changes to the files. It will be pushed to the gh-pages branch. Editing locally is easier for making major changes to the site, including more complex changes to theme content. It requires a local installation of Quarto and a basic text editor for editing theme content and git client to push your changes back to GitHub. See the Editing locally with Quarto section for details.

Editing in GitHub is easier for more minor content modifications such as editing text in individual markdowns file, one at a time. See the Editing online in GitHub section for details.

Editing locally with Quarto

This approach allows instantaneous rendering of the site exactly as it will appear in GitHub Pages so you can more rapidly iterate changes. Once you are happy with your changes, you can then commit them to your git branch locally, and push them with git to GitHub to update the online GitHub Pages site (or follow the GitHub PR workflow, if you prefer). Using git is outside the scope of this HOWTO, but lots of documentation and tutorial are available onine to learn git.

Download and install Quarto and a code editor of choice. Follow the instructions for previewing the website within your chosen code editor (e.g., VS Code).

Note that editing website content (i.e., Markdown files) requires reloading the preview page to see the changes, while editing a configuration file (i.e., yaml files) should trigger an automatic re-rendering of the website and updated preview.

Editing online in GitHub

When you are setting up a new documentation site initially, you will likely want to use the local Quarto approach described above to get your site configured. Once this has been accomplished and your site is running in GitHub Pages, you can make minor edits to your site directly on GitHub with your browser in three simple steps:

  1. Navigate to the file to be edited from the GitHub file browser (make sure you’re viewing the correct branch);
  2. Open it for editing by clicking on the “pencil” icon at the right side above the file content;
  3. Make all changes, preview them to make sure that everything is okay, and commit them to the docs branch (make sure that the “Commit directly to the docs branch” option is checked)

First publish to gh-pages

The first publish to gh-pages needs to be done locally.

  • On your local computer, open a terminal window and navigate to your repo directory.

  • Publish to the gh-pages:

    quarto publish gh-pages

    This is going to render the webpage and then push the _site contents to the gh-pages branch.

Step 3: Configuring the site

Currently, all of the website-level metadata that need to be changed are found in _metadata.yml.

  1. Provide a website title. This will show up at the top left of the site and in the browser tab

  2. Specifiy the site URL. This is for website itself. To find it, navigate to the rep landing page on GitHub, click “Settings”, then “Pages”. The site URL is the address at which the site is live.

  3. Specify the repo URL, the URL of the GitHub repository itself.

Commit the changes when done. That’s all there is to it.