eReefs Static Website

Setup

• Install Quarto v1.4.551
  • For some reason, the latest version of quarto doesn't display the css as expected.
  • wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.551/quarto-1.4.551-linux-amd64.deb
  • sudo dpkg -i quarto-1.4.551-linux-amd64.deb
• run quarto preview and confirm the website displays as expected.
• create and activate virtual env with python 3.9
• pip install -r requirements.txt

Previewing

To see a preview of the site, run quarto preview, or alternatively render the markdown to html with quarto render then run python3 -m http.server

IMPORTANT: The website sends requests to the eReefs API, which is on a different domain name than your localhost. This will cause the web browser to automatically reject the requests (CORS). To work around this issue, you can start your browser with the CORS security feature disabled.

Example:

chromium --disable-web-security --user-data-dir=/tmp/chromium-cors-test

Publishing

Publishing with GitHub Actions

Publishing with GitHub Actions set up initially according to the quarto documentation. However, the _publish.yml file was not generated by quarto publish gh-pages, which is not consistent with the documentation. The .github/workflows/publish.yml file has been set up to run the Quarto Publish on commits to the main branch. To publish with GitHub actions, push your changes to the main branch.

The publishing process includes a post render script to minify the javascript files. See the ./.github/workflows/publish.yml for details.

Publishing manually

Note that publishing with GitHub Actions is the recommended way of publishing. If you wish to publish manually, ensure you have the same version of quarto as specified in Setup section.

• Check out the branch you wish to deploy (ensure you have not checked out the gh-pages branch).
• run quarto publish gh-pages

This command will render the content, copy the output to the gh-pages branch, push that branch to GitHub.

Styling

Several eReefs websites exist, which are linked to in the dropdown menu of this website. This website has been styled with the Flatly theme, modified to align with the CSIRO website as it is likely the one most difficult to change.

Custom navigation

In order to match the styling of the CSIRO website, custom navigation was created. This was done because quarto supports only a pinned header, or a dynamically hidden header with headroom.js. In order to create this custom header:

• create the header with the _quarto.yml file
• render the page
• copy the code for the header
• put this code into the custom include (includes/_navbar_custom.qmd)
• change the header id="quarto-header" to id="custom-header"

When the website is built quarto will create its own header, which is why we have the javascript/remove_quarto_header.js file to remove it.

Development

The new version of the website was created by bringing across css and javascript from the old version. No time was spent looking into the files to see what unused functions, classes, etc, could be removed so there is a lot of redundant code relating to eAtlas.

Custom domain

The custom domain name is set up in GitHub. See the Pages section of the repository settings. The DNS for the custom domain is managed by AWS Route53. The domain is verified as owned by the GitHub organisation open-AIMS. This is done by a TXT record on Route53.