diff --git a/_quarto.yml b/_quarto.yml index 09ff007e7..41359cec7 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -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" diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd index 2f75c0487..5c2fc305c 100644 --- a/docs/authoring/brand.qmd +++ b/docs/authoring/brand.qmd @@ -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"} @@ -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"} --- @@ -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"} @@ -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"} --- @@ -131,6 +194,16 @@ format: --- ``` +Revealjs: + +```{.yaml filename="document.qmd"} +--- +format: + revealjs: + brand-mode: dark +--- +``` + ## Brand Elements @@ -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 @@ -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"} --- @@ -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 @@ -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 @@ -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"} @@ -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: @@ -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. @@ -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`. ::: diff --git a/docs/extensions/metadata.qmd b/docs/extensions/metadata.qmd index 249df0d6e..1e3ecb20a 100644 --- a/docs/extensions/metadata.qmd +++ b/docs/extensions/metadata.qmd @@ -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 diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index 79474349b..9dbdb16b2 100644 --- a/docs/journals/templates.qmd +++ b/docs/journals/templates.qmd @@ -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`. diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd index 30beb4b7e..87e988b37 100644 --- a/docs/output-formats/typst.qmd +++ b/docs/output-formats/typst.qmd @@ -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.