-
Notifications
You must be signed in to change notification settings - Fork 4
Quarto Profiles
Quarto is great, on that we all agree. It can render books and websites and blogs and dashboards and presentations. If you're clever, you can have it render all these formats in the same workflow job. Amazing.
With this functionality comes added complexity. Suddenly, a single _quarto.yml file will not suffice: the data portal definitely should not be included in the PDF. And the PDF formatting is messing up the website. And don't even get me started on the dashboard...
You need profiles. These are separate YAML files that correspond to separate build settings. Do you want to build a website and a full-length PDF and an executive summary PDF? Make three different profiles!
When Quarto renders, it searches for the file _quarto.yml. When using profiles, we restructure _quarto.yml to point Quarto towards other profile files. Our revamped _quarto.yml file should look something like this:
project:
type: book
book:
title: "2024 Alaska Electricity Trends Report"
author: "Alaska Center for Energy and Power"
description: An interactive report that summarizes federal, state, and utility electricity data for Alaska.
keyword: Alaska, energy, capacity, generation, price, rates
profile:
group:
- [pdf, html]
Then, we make the individual profile files. The naming structure is like this:
For a profile "pdf", make a YAML file called _quarto-pdf.yml. For the profile "html" make a YAML file called _quarto-html.yml.
Quarto will find these files during render and build accordingly.
Now that Quarto is pointed towards the profiles, we need to tailor each .yml file to our given format. For instance, _quarto-pdf.yml should only have settings applicable to PDF renderings, likewise for the HTML profile.
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.
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.
At this point, Quarto is set to render the different profile settings, but the GitHub Actions Workflow has no idea what's going on. Modify the steps of the job in order to use the correct profile. For example, the file .github/workflows/quarto-publish.yml should include code like this. Notice the QUARTO_PROFILE: field
- name: Publish to GitHub Pages (and render)
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
env:
QUARTO_PROFILE: html
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Render PDF
uses: quarto-dev/quarto-actions/render@v2
with:
to: pdf
path: .
env:
QUARTO_PROFILE: pdf
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
With this, Quarto should run different profiles when rendering via GitHub Actions build/deploy. There are some nuances, make sure to read up first. It's easy to make a mess, trust me.