AETR Web Book

Preliminary Alaska Electricity Trends Report as a web book.

Preview and Render Locally

Prepare the environment

Rendering this web-book requires R (>=4.4.0) and some R packages.

1. Install R from The Comprehensive R Archive Network using the correct method for your operating system.

2. Install OpenSSL, which is required for one of the packages.

3. The Barlow font (Regular and Bold) must be installed on your machine. This will be different for different operating systems.

   1. For Macs, follow the instructions for installing fonts via Font Book

   2. For Linux, manually perform the commands listed in this project's GitHub Workflow

4. Issue these commands on your command line (or however you access R) to prepare your R environment using renv:

% cd aetr-web-book-2024/
% R    # at the command line to start R
> renv::restore()

Previewing Locally

Web book Previewing describes viewing the website locally by using quarto preview on the command line to generate HTML from the qmd files. The generated HTML code goes in the _book/ directory. It should also automatically open a browser window. See quarto preview help for hints.

However, we use Profiles in this repository with three different configuration files which complicates local previewing somewhat.

1. _quarto.yml = the main configuration file that triggers the other two
2. _quarto-html.yml = configures the web book
3. _quarto-pdf.yml = configures the PDF report

If the default profile is not set in _quarto.yml, the quarto preview renders both, one after the other; however the second render clobbers the first so you can only view HTML or PDF depending on the order of the profile group. So in our case, it is better to specify which format you want to render with quarto preview --profile html or quarto preview --profile pdf, or to toggle default between the two by editing _quarto.yml.

VSCode and RStudio both render and preview pages automatically using a Preview button. In VSCode, open a .qmd page in the editor such as index.qmd, and hit shift-command-K to preview the page.

Publishing via GitHub

This project includes a GitHub Workflow that renders the Markdown as HTML and PDF and posts those to the gh-pages branch to create a website. You can see in that workflow that the two profiles are rendered sequentially with the PDF subsequently copied into the gh-pages branch to avoid the clobbering issue noted locally.

Note that rendered files and directories containing rendered files should be listed in .gitignore so they don't get copied into the GitHub repo. The presence of those files causes GitHub Actions to choke which breaks the generation and posting of the web book.

Credits

Website format is based on the Quarto Website Tutorial developed by Openscapes. Code is avalable in the tutorial GitHub repo.

This project was created using the cookiecutter-quarto-website template that utilizes the Cookiecutter project, but has many extensions not included in that template.