typst brand yml: move logo documentation out of advanced

and clean up

fixes quarto-dev/quarto-cli#12181

Author: gordonwoodhull

docs/advanced/typst/brand-yaml.qmd

@@ -17,31 +17,6 @@ Brand YAML palette and theme colors are available in Typst `brand-color`, e.g. `
 
 Lighter versions of the colors, suitable as background colors, are available in `brand-background-color`, e.g. `brand-background-color.success`.
 
-## Logo
-
-The `logo` option allows extra customization in Typst for full control over layout.
-
-In all formats, `logo` can be the path to a logo or the name of a `brand.logo` resource, i.e. `small`, `medium`, or `large`. It can also be an object with
-
-`path` 
-: Image path or name of `brand.logo` resource
-`alt`
-: Alt text for the logo image
-
-The Typst implementation also supports
-
-`width`
-: Width in CSS units. Default `1.5in`.
-
-`location`
-: Location on the page in X and Y using CSS [`text-align`](https://developer.mozilla.org/en-US/docs/Web/CSS/text-align) and [`text-vertical-align`](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align) keyword values, specifically
-`left`, `center`, `right` and `top`, `middle`, and `bottom`.
-  The X and Y components are combined with a dash, e.g. `left-top` (the default), `center-middle`, etc.
-  Applied as Typst [`align`](https://typst.app/docs/reference/layout/align/).
-
-`padding`, `padding-top`, `padding-right`, `padding-bottom`, `padding-left`
-: 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. Due to a limitation in the Lua implementation of YAML, multiple padding options are applied in alphabetical order instead of the order of the YAML object. Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset). Default `padding: 0.75in`.
-
 ## Typography
 
 Brand YAML is specified for the following elements and Brand YAML properties. Combinations that are not supported are marked NA.

docs/authoring/brand.qmd

@@ -242,6 +242,63 @@ The **brand.yml** specification allows you to specify a `light` and `dark` versi
 
 ::: 
 
+#### Document logo customization
+
+The document `logo` option allows extra customization of the logo.
+
+To choose a brand logo resource:
+```{.yaml filename="document.qmd"}
+---
+logo: large
+---
+```
+
+To choose a brand logo resource and change the alt text:
+
+```{.yaml filename="document.qmd"}
+---
+logo:
+  path: large
+  alt: Alternate alternate text
+---
+```
+
+::: {.callout-warning}
+
+## Limitation
+
+It is [not currently possible](https://github.com/quarto-dev/quarto-cli/issues/11309) to customize the logo for a specific page within a website. Only the project's `_brand.yml` is applied.
+
+::: 
+
+The Typst implementation allows customization of the logo position at the document level:
+
+```{.yaml filename="document.qmd"}
+---
+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`.                                                                                                                     |
++--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
 ### Typography
 
 [Typography in the **brand.yml** docs](https://posit-dev.github.io/brand-yml/brand/typography.html){.external}
@@ -521,14 +578,6 @@ You can learn more about layering themes in [More About Quarto Themes](/docs/out
 
 ### Typst
 
-If the document has [both light and dark brands](#dark-brand), use `brand-mode: dark` to produce a dark-background PDF that matches the dark brand of your website.
-
-``` yaml
-format:
-  typst:
-    brand-mode: dark
-```
-
 In Typst documents, brand colors are set in a [dictionary](https://typst.app/docs/reference/foundations/dictionary/) called `brand-color`. 
 You can access them directory in raw Typst blocks using the syntax `brand-color.COLOR_NAME`.
 For example, you could make a rectangle filled with your `primary` brand color:
@@ -607,4 +656,15 @@ theme:
     - brand
 ```
 
-Learn more about how Quarto generates styles in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).
+Learn more about how Quarto generates styles in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).
+
+## Choosing light or dark brand in Typst
+
+If the document has [both light and dark brands](#dark-brand), use `brand-mode: dark` to produce a dark-background PDF that matches the dark brand of your website.
+
+``` yaml
+format:
+  typst:
+    brand-mode: dark
+```
+