(s)css support with quarto use brand <source>

[gayol-openrxiv]

Description

I just started using quarto use brand <source> to apply my org's branding (from a public GitHub repo) and I noticed that any style docs (css or scss) are not downloaded into my project. It would be nice to also pull those and then be able to provide that path in the yaml.

Side note > I have found a workaround using jsdeliver to provide a link in the css value of the yaml:

format: revealjs: css: https://cdn.jsdelivr.net/gh/owner/repository@main/styles-file-path-from-root

[cderv]

Thanks for opening here from discord question.

Can you share an example of the brand yaml definition you tried with external file ?

Also did you consider Brand Extension to bundle and distribute your extension and its resources ?

This is usually the way to distribute like custom format or customer project.

I'll be curious to understand what works or not.

Thanks.

[mcanouil]

Adding a few details to @cderv's reply.

quarto use brand only copies the brand file itself, plus the logo images and the font files (source: file) it references.
Stylesheets aren't copied, whatever the source is.

brand.yml has no way to reference stylesheet files, so quarto use brand can't really do this, and a brand-only extension can't either.

A quick note on the two kinds of stylesheet, as they don't behave the same way.
SCSS files go under theme and are compiled together with the format's own theme, so they can use and override its Sass variables.
CSS files go under css and are linked as separate stylesheets, with no access to those Sass variables.

The way to ship your brand together with its stylesheets is a format extension that also contributes the brand.
For example, a repository with this layout:

_extensions/acme/_extension.yml
_extensions/acme/_brand.yml
_extensions/acme/brand.scss
template.qmd

With _extensions/acme/_extension.yml:

title: Acme
author: Acme
version: 1.0.0
quarto-required: ">=1.8.0"
contributes:
  metadata:
    project:
      brand: _brand.yml
  formats:
    revealjs:
      theme: [brand.scss]

And template.qmd:

---
title: "My presentation"
format: acme-revealjs
---

To start a new project from it, use quarto use template owner/repository.
This installs the extension and gives you a starter document.
To add it to an existing project, use quarto add owner/repository, and then quarto update extension owner/repository when the brand changes.

The important part is using the extension's format (acme-revealjs).
With plain revealjs, you still get the brand colours, fonts and logos from _brand.yml, but not the stylesheets.

If your styles are small, you can also write SCSS inline in _brand.yml under defaults.bootstrap (uses, functions, mixins, defaults and rules), and quarto use brand will bring it along.
This only applies to the html and dashboard formats, though, so it won't help with Reveal.js.

I'd use this with caution.
The whole brand is passed to Pandoc through an environment variable when rendering, so a large brand file can make Quarto fail (#13542).
It's also harder to maintain than a real stylesheet.
So keep it to a few rules, and use the extension for anything bigger.

About the jsDelivr link: it works for css because Pandoc accepts a URL there and writes it into the <link> tag.
Quarto doesn't document it, though, and it doesn't work for SCSS under theme, which Quarto has to read from disk to compile.
So it's fine for a plain CSS file, but it won't help if you move to SCSS.