Skip to content

unified brand, dark logo, etc #1779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 1, 2025
Merged

unified brand, dark logo, etc #1779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
319a778
unified brand, dark logo, etc
gordonwoodhull Sep 25, 2025
ba06ef7
brand shortcode light/dark updates
gordonwoodhull Sep 25, 2025
9ec9b7a
Update docs/authoring/brand.qmd
gordonwoodhull Sep 30, 2025
5463852
Update docs/authoring/brand.qmd
gordonwoodhull Sep 30, 2025
68e5c80
brand extension; typst page partial
gordonwoodhull Oct 1, 2025
49bee66
document typst brand-logo and brand-logo-images
gordonwoodhull Oct 1, 2025
23a84dc
upgrade callout to warning
gordonwoodhull Oct 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion _quarto.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -474,9 +474,10 @@ website:
- docs/extensions/formats.qmd
- docs/extensions/revealjs.qmd
- docs/extensions/project-types.qmd
- docs/extensions/starter-templates.qmd
- text: "Metadata Extensions"
href: docs/extensions/metadata.qmd
- docs/extensions/starter-templates.qmd
- docs/extensions/brand.qmd

- id: reference
title: "Reference"
Expand Down
214 changes: 156 additions & 58 deletions docs/authoring/brand.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ Quarto will detect the presence of `_brand.yml` and automatically apply the bran
You can create a `_brand.yml` file outside of a Quarto project (e.g. without a `_quarto.yml`).
In this case, `_brand.yml` will automatically apply to documents in the same directory.

```{.yaml filename="_brand.yml"}
color:
background: "#eeeeee"
```


You can also set brand options in a document by specifying brand elements under the `brand` option:

```{.yaml filename="document.qmd"}
Expand Down Expand Up @@ -73,9 +79,59 @@ brand: brand/_brand.yml

Paths specified in `_brand.yml` are relative to the location of the brand file.

### Dark Brand
### Light and Dark Colors

To specify colors for both light and dark modes using a single brand.yml file, specify any color in `color` or `typography` with an object containing the `light` and `dark` colors:

```{.yaml filename="_brand.yml"}
color:
background:
light: "#ffffff"
dark: "#333333"
foreground:
light: "#333333"
dark: "#ffffff"
typography:
headings:
color:
light: "#111144"
dark: "#d0d0ff"
```

This also works with the brand specified directly in the document metadata:

As with [Themes](/docs/output-formats/html-themes.qmd#dark-mode), you can specify both light and dark brands, making both a light and a dark version of your output available:

```{.yaml filename="document.qmd"}
---
brand:
color:
background:
light: "#ffffff"
dark: "#333333"
foreground:
light: "#333333"
dark: "#ffffff"
typography:
headings:
color:
light: "#111144"
dark: "#d0d0ff"
---
```


::: {.callout-warning}

## Limitation

Colors in [the `palette`](#color) cannot currently be specified with `light` and `dark` variants.

:::


### Light and Dark Brands

If you prefer to author separate light and dark brands for light and dark mode, or you need to customize non-color properties, you can separate the brands into their own files, and specify `light` and `dark` brand files:

```{.yaml filename="document.qmd"}
---
Expand All @@ -85,6 +141,8 @@ brand:
---
```

This is similar to how [Themes](/docs/output-formats/html-themes.qmd#dark-mode) work.

This also works with brands specified directly in the document:

```{.yaml filename="document.qmd"}
Expand All @@ -109,19 +167,24 @@ brand:
dark: dark-brand.yml
```


::: {.callout-warning}

## Limitation

The `revealjs` format does not support switching between light and dark modes.
Brand metadata cannot currently be specified directly in `_quarto.yml`, only via the file syntax.

:::
:::


#### Typst

To choose a dark brand in Typst output use `brand-mode: dark`:
### Brand Mode

The Typst and revealjs formats do not produce outputs which can toggle between light and dark mode dynamically.

By default, Typst and revealjs formats will render using the light brand.
Set `brand-mode: dark` to render using the dark brand.

Typst:

```{.yaml filename="document.qmd"}
---
Expand All @@ -131,6 +194,16 @@ format:
---
```

Revealjs:

```{.yaml filename="document.qmd"}
---
format:
revealjs:
brand-mode: dark
---
```


## Brand Elements

Expand Down Expand Up @@ -257,15 +330,7 @@ logo:
path: https://quarto.org/quarto.png
alt: "Quarto icon"
small: quarto-logo
```

::: {.callout-warning}

## Limitation

The **brand.yml** specification allows you to specify a `light` and `dark` version of your logo, but Quarto currently only uses the `light` version.

:::
```

#### Document logo customization

Expand All @@ -278,7 +343,15 @@ logo: large
---
```

Or, specify a brand logo and change the alt text:
Or override the brand logo for this document with a logo from a file:

```{.yaml filename="document.qmd"}
---
logo: logo.png
---
```

Or specify a brand logo resource and change the alt text:

```{.yaml filename="document.qmd"}
---
Expand All @@ -288,6 +361,21 @@ logo:
---
```

You can also individually customize light and dark logos, with any of the variations shown above:

```{.yaml filename="document.qmd"}
---
logo:
light:
path: large
alt: Alternate alternate text
dark:
path: dark-logo.png
alt: Alternate text for dark logo
---
```


::: {.callout-warning}

## Limitation
Expand All @@ -296,35 +384,7 @@ It is [not currently possible](https://github.com/quarto-dev/quarto-cli/issues/1

:::

The Typst implementation allows customization of the logo position at the document level:

```{.yaml filename="document.qmd"}
---
format:
typst:
logo:
width: 1in
location: right-top
padding-right: 0.5in
padding-top: 0.25in
alt: Alternate alternate text
---
```

+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| Option | Description |
+==========================+================================================================================================================================================+
| `width` | Width in CSS units. Default `1.5in`. |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| `location` | Location on the page in `X-Y`, where `X` is `left`, `center`, or `right` and Y is `top`, `middle`, or `bottom`. |
| | Applied as Typst [`align`](https://typst.app/docs/reference/layout/align/). |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| `padding`, `padding-top`,| Amount of padding to add to each side of the logo, using CSS [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) conventions.|
| `padding-right`, | Padding options are applied in alphabetical order. |
| `padding-bottom`, | Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset). |
| `padding-left` | Default `padding: 0.75in`. |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+

When using `format: typst` you can additionally [customize the logo position](../output-formats/typst.qmd#logo-position).

### Typography

Expand All @@ -342,13 +402,6 @@ typography:
The properties you can set for a font under `fonts` depends on the `source`. You can see the other properties available in our [Reference for Brand](/docs/reference/metadata/brand.qmd#font-resource-definitions).


::: {.callout-warning}
## Limitation

HTML formats do not currently support `source: file`.
:::


You can then refer to fonts by `family` in the remaining typography options:

``` {.yaml filename="_brand.yml"}
Expand Down Expand Up @@ -534,10 +587,20 @@ Beyond the automatic application of your brand file, you can also directly acces

Some values from the `_brand.yml` configuration file can be accessed via the `brand` shortcode. In particular, you can access colors and logos by name:

- Use `{{{< brand color COLOR_NAME BRAND_MODE >}}}` to return the brand color named `COLOR_NAME` as a string.
- Use `{{{< brand logo LOGO_NAME BRAND_MODE >}}}` to return the brand logo named `LOGO_NAME` as an image.
- Use `{{{< brand color COLOR_NAME VARIANT >}}}` to return the brand color named `COLOR_NAME` as a string.
- Use `{{{< brand logo LOGO_NAME VARIANT >}}}` to return the brand logo named `LOGO_NAME` as an image.

`VARIANT` is optional:

- For the `brand color` shortcode, the default is `light`. To return the color from the [dark brand](#dark-brand) use `dark`.
- For the `brand logo` shortcode, the default is `both`, which will expand to both light and dark logos with the appropriate [classes for mode-specific content](../output-formats/html-themes.qmd#mode-specific-content) so that the light logo shows in light mode and the dark logo shows in dark mode.

::: {.callout-note}

If the `VARIANT` is `light` or `dark`, the `brand logo` shortcode will not add a mode-specific class.

:::

The `BRAND_MODE` is optional and defaults to `light`. To return the color from the [dark brand](#dark-brand) use `dark`.

For example, you could use the shortcode to place a brand image you've named `icon` in a dashboard sidebar:

Expand Down Expand Up @@ -632,6 +695,26 @@ For example, you could make a rectangle filled with your `primary` brand color:
```
````

Brand logos are set in dictionaries called `brand-logo` and `brand-logo-images`.

For example, you can write Typst code to insert an image using its resolved path and alt text from `brand.logo.images`:

````{.markdown filename="document.qmd"}
---
format: typst
brand:
logo:
images:
custom:
path: custom.png
alt: custom logo
---

```{=typst}
#image(brand-logo-images.custom.path, alt=brand-logo-images.custom.alt)
```
````

### Lua API

Filters and shortcodes can access brand values using the `brand` Lua module.
Expand All @@ -641,11 +724,26 @@ local brand = require('modules/brand/brand')
local primary = brand.get_color('primary')
```

## Migrating to `_brand.yml`: use the `brand` string in `theme`
## Sharing brands across projects

::: callout-warning

Quarto requires all assets, including logos and font files, to live in a single directory tree with `_quarto.yml` at the root. Using a path to a `brand.yml` file outside of that directory tree will not work correctly.

:::

Quarto 1.8 introduces the [brand extension](../extensions/brand.qmd), a Quarto-specific way to distribute brand metadata and assets using a Git repository.

Quarto extensions install to the `_extensions/` subdirectory of your project. You will have a copy of the brand metadata and assets in each project; use [`quarto update`](../extensions/managing.qmd#updating) to update the brand extension from its repository.

Quarto 1.9 will introduce `quarto use brand` for a simpler way to share brands. Watch [this page on the prerelease documentation](https://prerelease.quarto.org/docs/authoring/brand.html#sharing-brands-across-projects) for availability.


## Combining brands and themes

::: callout-note

The following information is only necessary if you are migrating projects created with Quarto 1.5 and earlier to use `_brand.yml`.
The following information is only necessary if you want to combine bootswatch themes with `_brand.yml`.

:::

Expand Down
4 changes: 2 additions & 2 deletions docs/extensions/metadata.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ Currently, metadata extensions only merge project-level metadata. This limitatio

Here we'll describe how to create a simple metadata extension. We'll use the `quarto create` command to do this. If you are using VS Code, Positron, or RStudio you should execute `quarto create` within their respective integrated Terminal panes.

To get started, execute `quarto create extension metadata` within the parent directory where you'd like the filter extension to be created:
To get started, execute `quarto create extension metadata` within the parent directory where you'd like the metadata extension to be created:

```{.bash filename="Terminal"}
$ quarto create extension metadata
? Extension Name › my-prerender-scripts
```

As shown above, you'll be prompted for an extension name. Type `my-prerender-scripts` and press Enter---the filter extension is then created:
As shown above, you'll be prompted for an extension name. Type `my-prerender-scripts` and press Enter---the metadata extension is then created:

```bash
? Extension Name › my-prerender-scripts
Expand Down
4 changes: 4 additions & 0 deletions docs/journals/templates.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,10 @@ typst-template.typ

: The definition of the Typst template function that will be called on the entire document contents. In the default template this function is called `article()` and generates a title block and author list, followed by the document content, optionally laid out in columns.

page.typ

: Sets properties of the page such as size, margin, numbering, and background logo.

typst-show.typ

: A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`.
Expand Down
32 changes: 32 additions & 0 deletions docs/output-formats/typst.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,38 @@ fontsize: 11pt
---
```

## Logo Position

If there is a logo [from brand.yml](../authoring/brand.qmd#logo) or specified directly in the document, Quarto's Typst implementation allows customization of the logo position in the document (or project):

```{.yaml filename="document.qmd"}
---
format:
typst:
logo:
width: 1in
location: right-top
padding-right: 0.5in
padding-top: 0.25in
alt: Alternate alternate text
---
```

+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| Option | Description |
+==========================+================================================================================================================================================+
| `width` | Width in CSS units. Default `1.5in`. |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| `location` | Location on the page in `X-Y`, where `X` is `left`, `center`, or `right` and Y is `top`, `middle`, or `bottom`. |
| | Applied as Typst [`align`](https://typst.app/docs/reference/layout/align/). |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| `padding`, `padding-top`,| Amount of padding to add to each side of the logo, using CSS [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) conventions.|
| `padding-right`, | Padding options are applied in alphabetical order. |
| `padding-bottom`, | Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset). |
| `padding-left` | Default `padding: 0.75in`. |
+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+


## Computation Figure Format

Typst has great support for SVG graphics, so `format: typst` defaults to `fig-format: svg`. This configuration means executable code cells that produce images will produce `.svg` output.
Expand Down