diff --git a/_quarto.yml b/_quarto.yml index 602d294414..2549e4f792 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -136,6 +136,8 @@ website: href: docs/authoring/notebook-embed.qmd - docs/authoring/callouts.qmd - docs/authoring/code-annotation.qmd + - text: "Brand" + href: docs/authoring/brand.qmd - docs/authoring/article-layout.qmd - section: "Scholarly Writing" contents: diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd index c41f2c4ab7..21a8310748 100644 --- a/docs/authoring/brand.qmd +++ b/docs/authoring/brand.qmd @@ -1,101 +1,465 @@ --- title: Multiformat branding with `_brand.yml` -draft: true --- -## Introduction +::: callout-caution +## Work In Progress -Quarto supports a wide variety of formats, and allows powerful customization of your document's appearance -in each of those formats. -`_brand.yml` enables a different form of appearance customization. -This feature is particularly well-suited for organizations that need a unified look across multiple formats with little per-format work. +These docs are a work-in-progress and may be incorrect or incomplete. Feedback welcome. +::: + +## Overview + +Quarto supports [**brand.yml**](https://posit-dev.github.io/brand-yml/)---a single YAML file that can be used to customize the appearance of your documents across multiple formats. This is particularly useful for organizations that need a unified look across various formats. + +As an example, consider the following `_brand.yml` file: + +``` {.yaml filename="_brand.yml"} +color: + palette: + dark-grey: "#222222" + blue: "#ddeaf1" + background: blue + foreground: dark-grey + primary: black + +logo: + medium: logo.png + +typography: + fonts: + - family: Jura + source: google + base: Jura + headings: Jura +``` + +When this `_brand.yml` is placed in a project, webpages, presentations, PDF reports, and dashboards will share a common appearance: + +::::::: {.column-body-outset-right layout-ncol="4"} +::: {} +![Webpage: `html`](images/brand-html.png){.lightbox group="brand-formats" fig-alt="Screenshot of a webpage. The text is dark grey on a light blue background, using a rounded sans-serif typeface, a logo appears in the navbar."} +::: + +::: {} +![Dashboard `dashboard`](images/brand-dashboard.png){.lightbox group="brand-formats" fig-alt="Screenshot of a dashboard. The text is dark grey on a light blue background, using a rounded sans-serif typeface, a logo appears in the navbar."} +::: + +::: {} +![Presentation: `revealjs`](images/brand-revealjs.png){.lightbox group="brand-formats" fig-alt="Screenshot of a presentation. The text is dark grey on a light blue background, using a rounded sans-serif typeface, a logo appears in bottom left of the slide."} +::: + +:::{} +![PDF: `typst`](images/brand-typst.png){.lightbox group="brand-formats" fig-alt="Screenshot of a PDF document. The text is dark grey on a light blue background, using a rounded sans-serif typeface, a logo appears in top right of the page."} +::: +::: -## Hello, `_brand.yml` -Consider the following `hello-brand.qmd` document in a folder that contains the following `_brand.yml` file: +View the example: [Source](https://github.com/cwickham/quarto-examples/tree/brand/brand/brand-simple) | [Live website](https://charlotte.quarto.pub/brand-simple/) -::: {.panel-tabset} +On this page: -## `hello-brand.qmd` +- Learn how to add a brand file -```qmd +- Learn about the elements of **brand.yml** and how they are used in Quarto. + +- Learn how to access brand values outside of the brand file. + +- See a more comprehensive example. + +::: callout-warning +## Limitation + +The **brand.yml** specification is an active area of work at Posit. Quarto's support for **brand.yml** is not yet complete. For now, we've highlighted places where Quarto doesn't yet support the full spec with special **Limitation** callouts, like this one. + +Currently, the formats that support **brand.yml** are: `html`, `dashboard`, `revealjs` and `typst`. +::: + +## Applying Brand + +To specify a brand, create a `_brand.yml` file in the root directory of your project. *Do you need a project? Do we reccommend a project? * +Quarto will detect the presence of `_brand.yml` and automatically apply the brand to all documents of the supported formats in the project. + +You can also set, or override, brand settings in a document by specifying brand elements under the `brand` option: + +```{.yaml filename="document.qmd"} --- -format: - html: default - revealjs: default - dashboard: default - typst: default - pdf: default +brand: + color: + background: "#ffffff" +--- +``` + +You can disable brand for a document by setting `brand` to `false`: + +```{.yaml filename="document.qmd"} +--- +brand: false +--- +``` + +You can put `_brand.yml` in a subdirectory of your project, and then use the `brand` key to specify the path to the brand file. +For example, to the the brand file at `brand/_brand.yml` for a single document, add `brand` to the header: + +```{.yaml filename="document.qmd"} --- +brand: brand/_brand.yml +--- +``` + +To use the brand file at `brand/_brand.yml` for all documents in the project add `brand` to `_quarto.yml`: + +```{.yaml filename="_quarto.yml"} +brand: brand/_brand.yml +``` + +Paths specified in `_brand.yml` are relative to the location of the brand file. (*Is this true?*) + +## Brand Elements + +The elements of **brand.yml** are specified in the specification at . In this section, learn how these elements are used in Quarto. + +### Color + + -## Hello, `_brand.yml` +Use `color` to define your brand's color palette and map your palette to the roles colors play, a.k.a semantic colors. A simple example might define the value `background` to a light blue: -Find out more in the [documentation](https://prerelease.quarto.org/docs/authoring/brand.html) +``` {.yaml filename="_brand.yml"} +color: + background: "#ddeaf1" +``` +Use the `palette` key to define a set of named colors that can be referenced elsewhere in the `_brand.yml`. For example, you might define `blue` and set it as the `background`: + +``` {.yaml filename="_brand.yml"} +color: + palette: + blue: "#ddeaf1" + background: blue ``` -## `_brand.yml` +The most commonly set colors include `foreground`, `background` and `primary`: -```yml +``` {.yaml filename="_brand.yml"} color: - with: - orange: '#a55930' - primary: orange + palette: + dark-grey: "#222222" + blue: "#ddeaf1" + background: blue + foreground: dark-grey + primary: black ``` +The colors `foreground` and `background` are used consistently across formats to set the color of the main text and color of the page it appears on. +The color `primary` sets the link color, navbar color (`html` and `dashboard`), and progress bar color (`revealjs`). + +For HTML formats that use Bootstrap (`html`, `dashboard`) the remaining semantic colors are mapped directly to their Bootstrap counterparts with the same name. + +::: {.callout-tip collapse="true"} + +## Full list of semantic colors + +The full list of semantic colors you can set in `color` is: + ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| Name | Description | ++=======================+===============================================================================================================================+ +| `foreground` | The main text color. Typically will be close to black and must have high contrast with the background color. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `background` | The main background color. Tyically will be close to white and must have high contrast with the foreground color. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `primary` | The primary accent color, used for hyperlinks, active states, and primary action buttons. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `secondary` | The secondary accent color, often used for lighter text or disabled states. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `tertiary` | The tertiary accent color, used for hover states, accents, and wells. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `success` | The color used for positive or successful actions and information. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `info` | The color used for neutral or informational actions and information. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `warning` | The color used for warning or cautionary actions and information. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `danger` | The color used for errors, dangerous actions, or negative information. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `light` | A bright color, used as a high-contrast foreground color on dark elements or low-contrast background color on light elements. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +| `dark` | A dark color, used as a high-contrast foreground color on light elements or high-contrast background color on light elements. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ + ::: -These are the resulting documents: +You can access both named and semantic colors from your brand in SCSS and using the `brand` shortcode. See [Using `_brand.yml` values](#using-brand-values) for more details. + +### Logo + + + +Use `logo` to specify the logo for your brand: -::: {.panel-tabset} +``` {.yaml filename="_brand.yml"} +logo: + medium: logo.png +``` + +You can specify a local file path, relative to the location of `_brand.yml` or a URL (*is this true?*). + +A single logo may not work well in all locations so **brand.yml** allows you to set 3 different logos: `small`, `medium` and `large`. For example: + +``` {.yaml filename="_brand.yml"} +logo: + small: logo-small.png + medium: logo.png + large: logo-large.png +``` + +You don't need to specify all three---Quarto will use what you provide based on the following preferences: + ++----------------------+----------------------------------------------+-------------------------------+ +| Format | Location | Logo Preference (high to low) | ++======================+==============================================+===============================+ +| `html` | Top navigation bar | `small`\> `medium`\>`large` | ++----------------------+----------------------------------------------+-------------------------------+ +| `html` | Side navigation | `medium`\>`small`\>`large` | ++----------------------+----------------------------------------------+-------------------------------+ +| `dashboard` | | Same as website. | ++----------------------+----------------------------------------------+-------------------------------+ +| `typst` | Top left, control with `format: typst: logo` | `medium`\>`small`\>`large` | ++----------------------+----------------------------------------------+-------------------------------+ +| `revealjs` | Bottom right corner of slides | `medium`\>`small`\>`large` | ++----------------------+----------------------------------------------+-------------------------------+ + +You can also specify named logos under `images` which you can reference in `small`, `medium` and `large`. In particular, this allows you to set alternative text for your logos using `alt`: + +``` {.yaml filename="_brand.yml"} +logo: + images: + quarto: + path: https://quarto.org/quarto.png + alt: "Quarto icon" + small: quarto +``` -## `html` +::: {.callout-warning} -TBF. +## Limitation -## `dashboard` +The **brand.yml** specification allows you to specify a `light` and `dark` version of your logo, but Quarto currently only uses the `light` version. -TBF. +::: -## `revealjs` +### Typography -TBF. + -## `typst` +The `typography` element allows you to specify fonts and their style. Use `fonts` to specify a list of fonts to use for your brand: -TBF. +``` {.yaml filename="_brand.yml"} +typography: + fonts: + - family: Jura + source: google +``` -## `pdf` +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). -TBF. +You can then refer to fonts by `family` in the remaining typography options: +``` {.yaml filename="_brand.yml"} +typography: + fonts: + - family: Jura + source: google + base: Jura + headings: Jura +``` + +The options `base` and `headings` set the typographic style of the main text and headings respectively. +Use `links` to apply specific styles to links. +The option `monospace` sets the typographic style of code in general, and `monospace-inline` and `monospace-block` can be further used to style code that appears inline and in blocks respectively. + +``` {.yaml filename="_brand.yml"} +# More comprehensive example +# inlcude styling code +``` + +The fields allowed for each element differ, expand the callout below to see what is supported in each field. + +::: {.callout-tip collapse="true"} + +## Full set of text elements and supported fields. + +The full set of text elements that you can style with `typography` is: + ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| Attribute | Description | Supported Fields | ++====================+========================================================================================================+========================+ +| `base` | Default text, primarily used in the document body. | - `family` | +| | | - `size` | +| | | - `line_height` | +| | | - `weight` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| `headings` | All heading levels (h1, h2, etc.). | - `family` | +| | | - `weight` | +| | | - `style` | +| | | - `line_height` | +| | | - `color` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| `monospace` | General monospaced text, typically used in code blocks and other programming-related content. | - `family` | +| | | - `size` | +| | | - `weight` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| `monospace_inline` | Inline monospaced text, usually used for code snippets within regular text. Inherits from `monospace`. | - `family` | +| | | - `size` | +| | | - `weight` | +| | | - `color` | +| | | - `background_color` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| `monospace_block` | Block (multi-line) monospaced text, typically used for code blocks. Inherits from `monospace`. | - `family` | +| | | - `size` | +| | | - `weight` | +| | | - `line_height` | +| | | - `color` | +| | | - `background_color` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +| `link` | Hyperlinks. | - `weight` | +| | | - `color` | +| | | - `background_color` | +| | | - `decoration` | ++--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ + +The supported fields are generally described as follows: + +- `family`: The font family to be used for a typographic element. This should match a font resource declared in `typography.fonts`. + +- `size`: The font size for a typographic element. Should be specified using a CSS length unit (e.g., "14px", "1em", "0.9rem"). + +- `weight`: The font weight (or boldness) of the text. Can be a numeric value between 100 and 900, or a string like "normal" or "bold". + +- `style`: The font style for the text, typically either "normal" or "italic". + +- `line_height`: The line height of the text, which refers to the vertical space between lines. Often expressed as a multiple of the font size or in fixed units. + +- `color`: The color of the text. Can be any CSS-compatible color definition or a reference to a color defined in the brand's color palette. + +- `background_color`: The background color for the text element. Can be any CSS-compatible color definition or a reference to a color defined in the brand's color palette. + +- `decoration`: The text decoration, typically used for links. Common values include "underline", "none", or "overline". + +::: + +### Defaults + + + +The `defaults` section of **brand.yml** allows users to set option for specific tools that don't otherwise fit into the **brand.yml** schema. In particular, Quarto supports `defaults: quarto` and `defaults: bootstrap`. + +#### Quarto + +Quarto merges options you set in `defaults: quarto` with document metadata. For example, you can use this to set format specific options like syntax highlighting for `html`: + +``` {.yaml filename="_brand.yml"} +defaults: + quarto: + format: + html: + highlight-style: github +``` + +Or, you might change the `logo` options for `typst`: + +``` {.yaml filename="_brand.yml"} +defaults: + quarto: + format: + typst: + logo: + location: left-bottom +``` + +::: callout-note +## Set all formats in document metadata + +Because of the merging behavior of `format`, if you set format specific options in `defaults: quarto`, you'll need to set all the required formats in document metadata: + +``` {.yaml filename="document.qmd"} +format: + html: default + revealjs: default +``` ::: -## Using `_brand.yml` values +#### Bootstrap + +*How relevant is `defaults: bootstrap`? Example? WHere do you find out what you can put under `bootstrap`?* + +### Meta + + + +You can set brand metadata using the `meta` key: + +``` {.yaml filename="_brand.yml"} +meta: + name: Acme Corporation + link: https://www.acmecorp.com +``` + +::: {.callout-warning} + +## Limitation + +Quarto does nothing with `meta` values. + +::: + + +## Using `_brand.yml` values {#using-brand-values} ### Shortcode - `{{{< brand >}}}` Values from the `_brand.yml` configuration file can be accessed via the `brand` shortcode. -- `{{{< brand color COLOR_NAME >}}}` resolves `COLOR_NAME` to the appropriate color value -- `{{{< brand logo LOGO_NAME >}}} -- TBD: what should `{{{< brand typography ... >}}}` resolve to? +- `{{{< brand color COLOR_NAME >}}}` resolves `COLOR_NAME` to the appropriate color value +- `{{{< brand logo LOGO_NAME >}}}` -### Lua API +### In SCSS -```lua -local brand = require('modules/brand/brand') -local primary = brand.get_color('primary') +If `_brand.yml` defines `color: blue`: + +```{.yaml filename="_brand.yml"} +color: + palette: + blue: "#ddeaf1" +``` + +This should work: + +```{.scss filename="custom.scss"} +/*-- scss:defaults --*/ +$navbar-bg: $brand-blue; ``` -## Spec +### Revealjs -TBF. Link to posit-wide documentation? +### Typst -### `color` +Brand colors are available in `brand-color`: -### `typography` +````markdown +```{=typst} +#set text(fill: brand-color.primary) +``` +```` + +### Lua API + +``` lua +local brand = require('modules/brand/brand') +local primary = brand.get_color('primary') +``` -### `logo` +## Comprehensive Example -### `defaults` +TBD \ No newline at end of file diff --git a/docs/authoring/images/brand-dashboard.png b/docs/authoring/images/brand-dashboard.png new file mode 100644 index 0000000000..33a89fa6e9 Binary files /dev/null and b/docs/authoring/images/brand-dashboard.png differ diff --git a/docs/authoring/images/brand-html.png b/docs/authoring/images/brand-html.png new file mode 100644 index 0000000000..70536976ed Binary files /dev/null and b/docs/authoring/images/brand-html.png differ diff --git a/docs/authoring/images/brand-revealjs.png b/docs/authoring/images/brand-revealjs.png new file mode 100644 index 0000000000..b2856c01e6 Binary files /dev/null and b/docs/authoring/images/brand-revealjs.png differ diff --git a/docs/authoring/images/brand-typst.png b/docs/authoring/images/brand-typst.png new file mode 100644 index 0000000000..96de2f3b2e Binary files /dev/null and b/docs/authoring/images/brand-typst.png differ diff --git a/docs/prerelease/1.6/_highlights.qmd b/docs/prerelease/1.6/_highlights.qmd index b0f29cfff8..a594ba8677 100644 --- a/docs/prerelease/1.6/_highlights.qmd +++ b/docs/prerelease/1.6/_highlights.qmd @@ -1,5 +1,7 @@ Quarto 1.6 includes the following new features: +- [Support for **brand.yml**](/docs/authoring/brand.qmd): Customize the appearance of your Quarto documents across formats with a single `_brand.yml` file. + - `{{{< contents >}}}` shortcode: Use this shortcode to flexibly rearrange the contents of your document, including moving the results of an executable code cell. See the [documentation for more](/docs/authoring/contents.qmd). - [Landscape mode](/docs/authoring/article-layout.qmd#landscape-mode) blocks: Use fenced divs with class `.landscape` to set portions of `docx`, `pdf` and `typst` documents to landscape. Thanks to [`@edvinsyk`](https://github.com/edvinsyk)! \ No newline at end of file