finish brand-template

_quarto.yml

@@ -31,8 +31,7 @@ website:
           - brand/logo.qmd
           - brand/color.qmd
           - brand/typography.qmd
-          - brand/options.qmd
-          - brand/variables-and-format.qmd
+          - brand/template.qmd
     - id: examples-brands
       title: Example Brand Guidelines
       contents: "examples/brand-guidelines/*/index.qmd"

brand/index.qmd

@@ -15,11 +15,10 @@ brand-fonts: >
 brand-typography: >
   Font family, weight, style, color, and line height for key elements, 
   e.g. base, headings and monospace text.
-brand-options: >
-  Non-color related theme options, e.g. border radius, use of shadows or transparency, etc.
-brand-variables: >
-  Format-specific style variables and options. Style variables would be used by the various
-  pre-processors and the `format` item could be merged into the quarto `format` frontmatter key.
+brand-template: >
+  Additional context-specific settings beyond the basic brand colors and typography.
+  These could be options that are folded into existing Quarto yaml fields
+  like `format` or `website`, or they could be new fields for other contexts like `shiny`.
 ---
 
 
@@ -46,19 +45,16 @@ typography:
   headings: # <6>
   monospace: # <6>
 
-options: # <7>
-  # basic non-color theme settings # <7>
-
-variables: # <8>
-  html: ~ # <8>
-  pdf: ~ # <8>
-  remarkjs: ~ # <8>
-  <format>: ~ # <8>
-
-format: # <8>
-  html: ~ # <8>
-  pdf: ~ # <8>
-  <format>: ~ # <8>
+template: # <7>
+  format: # <7>
+    # basic format-specific settings  # <7>
+    html: # <7>
+    pdf:  # <7>
+    revealjs: # <7>
+  website: # <7>
+    # website specific settings # <7>
+  shiny: # <7>
+    # shiny specific settings # <7>
 ```
 
 1. [meta](meta.qmd): {{< meta brand-meta >}}
@@ -73,9 +69,7 @@ format: # <8>
 
 1. [typography](typography.qmd#typography): {{< meta brand-typography >}}
 
-1. [options](options.qmd): {{< meta brand-options >}}
-
-1. [variables, format](variables-and-format.qmd): {{< meta brand-variables >}}
+1. [template](template.qmd): {{< meta brand-template >}}
 
 ## Description
 
@@ -97,11 +91,8 @@ format: # <8>
 [typography](typography.qmd#typography)
 :    {{< meta brand-typography >}}
 
-[options](options.qmd)
-:    {{< meta brand-options >}}
-
-[variables, format](variables-and-format.qmd)
-:    {{< meta brand-variables >}}
+[template](template.qmd)
+:    {{< meta brand-template >}}
 
 ## YAML Schema
 

brand/spec/brand-template.yml

@@ -0,0 +1,31 @@
+- id: brand-template
+  description: >
+    Additional format or output-specific options, used as a template
+    for these settings in those contexts.
+  object:
+    properties:
+      format:
+        description: Quarto format options.
+        schema: object
+      website:
+        description: Quarto `website` options.
+        schema: object
+      book:
+        description: Quarto `book` options.
+        schema: object
+      bootstrap:
+        description: Bootstrap theme settings, similar to `bslib::bs_theme()`.
+        object:
+          closed: true
+          properties:
+            uses: string
+            functions: string
+            defaults:
+              description: Sass variables.
+              schema: object
+              namingConvention: kebab-case
+            mixins: string
+            rules: string
+      shiny:
+        description: Settings specific to Shiny applications.
+        schema: object

brand/spec/brand.yml

@@ -13,3 +13,7 @@
 - name: typography
   schema:
     ref: brand-typography
+
+- name: template
+  schema:
+    ref: brand-template

brand/template.qmd

@@ -0,0 +1,87 @@
+---
+title: Template
+pagetitle: "template | brand.yml"
+---
+
+## About
+
+Individual formats and outputs can expose format-specific variables or options that are relevant to themes, but that can't be set globally.
+
+For example, [Quarto slides expose a set of Sass variables](https://quarto.org/docs/presentations/revealjs/themes.html#sass-variables) while HTML documents and Shiny apps [use Sass variables set by Bootstrap](https://rstudio.github.io/bslib/articles/bs5-variables/index.html).
+
+On the other hand, some theme-relevant settings are actually format options, or are built on top of a base of format options.
+For example, when creating a branded Beamer presentation, its often easier to start with a known `theme` or `colortheme`.
+Or similarly, it might be easier in Bootstrap to start with a [Bootswatch theme](https://bootswatch.com/).
+
+A source of inspiration for this section is [pkgdown's approach to template packaging](https://pkgdown.r-lib.org/articles/customise.html#template-packages), where a source template provides the initial values for `_pkgdown.yml` settings that can be overridden in local instances.
+In this regard, the `template` section provides a template for the initial values of format- or output-specific settings.
+An alternative name for this section could be `settings`.
+
+
+## Example
+
+```{.yaml filename="brand.yml"}
+template:
+  format:
+    html:
+      toc: true
+      toc-location: left
+    beamer:
+      navigation: horizontal
+      theme: AnnArbor
+      colortheme: lily
+  bootstrap:
+    defaults:
+      enable-rounded: false
+      link-decoration: none
+  website:
+    body-footer: Copyright 2022-2024 Posit Software, PBC
+```
+
+## Spec
+
+```{.yaml}
+{{< include spec/brand-template.yml >}}
+```
+
+## Sources
+
+### Bootstrap
+
+Some of the most basic non-color concepts found in
+
+* <https://getbootstrap.com/docs/5.3/customize/options/>
+* <https://getbootstrap.com/docs/5.3/customize/css-variables/>
+
+If we have a `template.bootstrap` field, it would support the named section used by [theme Sass files in Quarto](https://quarto.org/docs/output-formats/html-themes-more.html).
+
+
+#### HTML basic options
+
+Example from [Quarto HTML documentation](https://quarto.org/docs/output-formats/html-themes.html#basic-options):
+
+```{.markdown}
+---
+title: "My Document"
+format:
+  html: 
+    theme: cosmo
+    fontsize: 1.1em
+    linestretch: 1.7
+---
+```
+
+#### Beamer options
+
+Example from [Quarto slides with beamer documentation](https://quarto.org/docs/presentations/beamer.html#beamer-options)
+
+```{.markdown}
+---
+format: 
+  beamer: 
+    aspectratio: 32
+    navigation: horizontal
+    theme: AnnArbor
+    colortheme: lily
+---
+```