You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -36,6 +36,12 @@ Quarto will detect the presence of `_brand.yml` and automatically apply the bran
36
36
You can create a `_brand.yml` file outside of a Quarto project (e.g. without a `_quarto.yml`).
37
37
In this case, `_brand.yml` will automatically apply to documents in the same directory.
38
38
39
+
```{.yaml filename="_brand.yml"}
40
+
color:
41
+
background: "#eeeeee"
42
+
```
43
+
44
+
39
45
You can also set brand options in a document by specifying brand elements under the `brand` option:
40
46
41
47
```{.yaml filename="document.qmd"}
@@ -73,9 +79,59 @@ brand: brand/_brand.yml
73
79
74
80
Paths specified in `_brand.yml` are relative to the location of the brand file.
75
81
76
-
### Dark Brand
82
+
### Light and Dark Colors
83
+
84
+
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:
85
+
86
+
```{.yaml filename="_brand.yml"}
87
+
color:
88
+
background:
89
+
light: "#ffffff"
90
+
dark: "#333333"
91
+
foreground:
92
+
light: "#333333"
93
+
dark: "#ffffff"
94
+
typography:
95
+
headings:
96
+
color:
97
+
light: "#111144"
98
+
dark: "#d0d0ff"
99
+
```
100
+
101
+
This also works with the brand specified directly in the document metadata:
77
102
78
-
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:
103
+
104
+
```{.yaml filename="document.qmd"}
105
+
---
106
+
brand:
107
+
color:
108
+
background:
109
+
light: "#ffffff"
110
+
dark: "#333333"
111
+
foreground:
112
+
light: "#333333"
113
+
dark: "#ffffff"
114
+
typography:
115
+
headings:
116
+
color:
117
+
light: "#111144"
118
+
dark: "#d0d0ff"
119
+
---
120
+
```
121
+
122
+
123
+
::: {.callout-warning}
124
+
125
+
## Limitation
126
+
127
+
Colors in [the `palette`](#color) cannot currently be specified with `light` and `dark` variants.
128
+
129
+
:::
130
+
131
+
132
+
### Light and Dark Brands
133
+
134
+
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:
79
135
80
136
```{.yaml filename="document.qmd"}
81
137
---
@@ -85,6 +141,8 @@ brand:
85
141
---
86
142
```
87
143
144
+
This is similar to how [Themes](/docs/output-formats/html-themes.qmd#dark-mode) work.
145
+
88
146
This also works with brands specified directly in the document:
89
147
90
148
```{.yaml filename="document.qmd"}
@@ -109,19 +167,24 @@ brand:
109
167
dark: dark-brand.yml
110
168
```
111
169
112
-
113
170
::: {.callout-warning}
114
171
115
172
## Limitation
116
173
117
-
The `revealjs` format does not support switching between light and dark modes.
174
+
Brand metadata cannot currently be specified directly in `_quarto.yml`, only via the file syntax.
118
175
119
-
:::
176
+
:::
120
177
121
178
122
-
#### Typst
123
179
124
-
To choose a dark brand in Typst output use `brand-mode: dark`:
180
+
### Brand Mode
181
+
182
+
The Typst and revealjs formats do not produce outputs which can toggle between light and dark mode dynamically.
183
+
184
+
By default, Typst and revealjs formats will render using the light brand.
185
+
Set `brand-mode: dark` to render using the dark brand.
186
+
187
+
Typst:
125
188
126
189
```{.yaml filename="document.qmd"}
127
190
---
@@ -131,6 +194,16 @@ format:
131
194
---
132
195
```
133
196
197
+
Revealjs:
198
+
199
+
```{.yaml filename="document.qmd"}
200
+
---
201
+
format:
202
+
revealjs:
203
+
brand-mode: dark
204
+
---
205
+
```
206
+
134
207
135
208
## Brand Elements
136
209
@@ -257,15 +330,7 @@ logo:
257
330
path: https://quarto.org/quarto.png
258
331
alt: "Quarto icon"
259
332
small: quarto-logo
260
-
```
261
-
262
-
::: {.callout-warning}
263
-
264
-
## Limitation
265
-
266
-
The **brand.yml** specification allows you to specify a `light` and `dark` version of your logo, but Quarto currently only uses the `light` version.
267
-
268
-
:::
333
+
```
269
334
270
335
#### Document logo customization
271
336
@@ -278,7 +343,15 @@ logo: large
278
343
---
279
344
```
280
345
281
-
Or, specify a brand logo and change the alt text:
346
+
Or override the brand logo for this document with a logo from a file:
347
+
348
+
```{.yaml filename="document.qmd"}
349
+
---
350
+
logo: logo.png
351
+
---
352
+
```
353
+
354
+
Or specify a brand logo resource and change the alt text:
282
355
283
356
```{.yaml filename="document.qmd"}
284
357
---
@@ -288,6 +361,21 @@ logo:
288
361
---
289
362
```
290
363
364
+
You can also individually customize light and dark logos, with any of the variations shown above:
365
+
366
+
```{.yaml filename="document.qmd"}
367
+
---
368
+
logo:
369
+
light:
370
+
path: large
371
+
alt: Alternate alternate text
372
+
dark:
373
+
path: dark-logo.png
374
+
alt: Alternate text for dark logo
375
+
---
376
+
```
377
+
378
+
291
379
::: {.callout-warning}
292
380
293
381
## Limitation
@@ -296,35 +384,7 @@ It is [not currently possible](https://github.com/quarto-dev/quarto-cli/issues/1
296
384
297
385
:::
298
386
299
-
The Typst implementation allows customization of the logo position at the document level:
|`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.|
323
-
|`padding-right`, | Padding options are applied in alphabetical order. |
324
-
|`padding-bottom`, | Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset). |
When using `format: typst` you can additionally [customize the logo position](../output-formats/typst.qmd#logo-position).
328
388
329
389
### Typography
330
390
@@ -342,13 +402,6 @@ typography:
342
402
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).
343
403
344
404
345
-
::: {.callout-warning}
346
-
## Limitation
347
-
348
-
HTML formats do not currently support `source: file`.
349
-
:::
350
-
351
-
352
405
You can then refer to fonts by `family` in the remaining typography options:
353
406
354
407
```{.yaml filename="_brand.yml"}
@@ -534,10 +587,20 @@ Beyond the automatic application of your brand file, you can also directly acces
534
587
535
588
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:
536
589
537
-
- Use `{{{< brand color COLOR_NAME BRAND_MODE >}}}` to return the brand color named `COLOR_NAME` as a string.
538
-
- Use `{{{< brand logo LOGO_NAME BRAND_MODE >}}}` to return the brand logo named `LOGO_NAME` as an image.
590
+
- Use `{{{< brand color COLOR_NAME VARIANT >}}}` to return the brand color named `COLOR_NAME` as a string.
591
+
- Use `{{{< brand logo LOGO_NAME VARIANT >}}}` to return the brand logo named `LOGO_NAME` as an image.
592
+
593
+
`VARIANT` is optional:
594
+
595
+
- For the `brand color` shortcode, the default is `light`. To return the color from the [dark brand](#dark-brand) use `dark`.
596
+
- 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.
597
+
598
+
::: {.callout-note}
599
+
600
+
If the `VARIANT` is `light` or `dark`, the `brand logo` shortcode will not add a mode-specific class.
601
+
602
+
:::
539
603
540
-
The `BRAND_MODE` is optional and defaults to `light`. To return the color from the [dark brand](#dark-brand) use `dark`.
541
604
542
605
For example, you could use the shortcode to place a brand image you've named `icon` in a dashboard sidebar:
543
606
@@ -632,6 +695,26 @@ For example, you could make a rectangle filled with your `primary` brand color:
632
695
```
633
696
````
634
697
698
+
Brand logos are set in dictionaries called `brand-logo` and `brand-logo-images`.
699
+
700
+
For example, you can write Typst code to insert an image using its resolved path and alt text from `brand.logo.images`:
Filters and shortcodes can access brand values using the `brand` Lua module.
@@ -641,11 +724,26 @@ local brand = require('modules/brand/brand')
641
724
localprimary=brand.get_color('primary')
642
725
```
643
726
644
-
## Migrating to `_brand.yml`: use the `brand` string in `theme`
727
+
## Sharing brands across projects
728
+
729
+
::: callout-warning
730
+
731
+
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.
732
+
733
+
:::
734
+
735
+
Quarto 1.8 introduces the [brand extension](../extensions/brand.qmd), a Quarto-specific way to distribute brand metadata and assets using a Git repository.
736
+
737
+
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.
738
+
739
+
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.
740
+
741
+
742
+
## Combining brands and themes
645
743
646
744
::: callout-note
647
745
648
-
The following information is only necessary if you are migrating projects created with Quarto 1.5 and earlier to use`_brand.yml`.
746
+
The following information is only necessary if you want to combine bootswatch themes with`_brand.yml`.
0 commit comments