brand extension

fixes #12559

this extension builds on the metadata extension, providing a sample brand.yml

to do this, we need to look at the project's project.brand and not just brand

Author: gordonwoodhull

news/changelog-1.8.md

@@ -95,6 +95,10 @@ All changes included in 1.8:
 
 - ([#12965](https://github.com/quarto-dev/quarto-cli/issues/12965)): Prevent automatic opening of new editor sessions when creating projects in Posit Workbench context. The `--open` flag is now ignored in this environment to avoid issues with Workbench session management.
 
+## Extensions
+
+- ([#12559](https://github.com/quarto-dev/quarto-cli/issues/12559)): New extension type: `brand` for distributing [brand.yml](https://posit-dev.github.io/brand-yml/) configurations with associated assets.
+
 ## Engines
 
 - ([#13171](https://github.com/quarto-dev/quarto-cli/pull/13171/)): Provide execution information to all engines uniformly via QUARTO_EXECUTE_INFO environment variable. It points to a file on disk containing a JSON object describing the execution environment for code cells to use.

src/command/create/artifacts/extension.ts

@@ -41,6 +41,7 @@ const kExtensionTypes: Array<string | ExtensionType> = [
   { name: "journal format", value: "journal", openfiles: ["template.qmd"] },
   { name: "custom format", value: "format", openfiles: ["template.qmd"] },
   { name: "metadata", value: "metadata", openfiles: [] },
+  { name: "brand", value: "brand", openfiles: [] },
 ];
 
 const kExtensionSubtypes: Record<string, string[]> = {

src/extension/extension.ts

@@ -791,7 +791,7 @@ async function readExtension(
   const metadata = contributes?.metadata as Record<string, unknown> | undefined;
 
   // resolve metadata/project pre- and post-render scripts to their full path
-  for (const key of ["pre-render", "post-render"]) {
+  for (const key of ["pre-render", "post-render", "brand"]) {
     for (const object of [metadata, project]) {
       if (!object?.project || typeof object.project !== "object") {
         continue;
@@ -808,8 +808,14 @@ async function readExtension(
           [],
         );
         if (resolved.include.length > 0) {
-          (object.project as Record<string, unknown>)[key] = resolved
-            .include;
+          if (key === "brand") {
+            (object.project as Record<string, unknown>)[key] = relative(
+              join(extensionDir, "..", ".."),
+              resolved.include[0],
+            );
+          } else {
+            (object.project as Record<string, unknown>)[key] = resolved.include;
+          }
         }
       }
     }

src/project/project-shared.ts

@@ -560,10 +560,14 @@ export async function projectResolveBrand(
     let fileNames = ["_brand.yml", "_brand.yaml"].map((file) =>
       join(project.dir, file)
     );
-    const brand = project?.config?.brand as boolean | string | {
-      light?: string;
-      dark?: string;
-    };
+    const brand = (project?.config?.brand ??
+      project?.config?.project.brand) as
+        | boolean
+        | string
+        | {
+          light?: string;
+          dark?: string;
+        };
     if (brand === false) {
       project.brandCache.brand = undefined;
       return project.brandCache.brand;

src/resources/create/extensions/brand/.gitignore

@@ -0,0 +1,3 @@
+*.html
+*.pdf
+*_files/

src/resources/create/extensions/brand/README.ejs.md

@@ -0,0 +1,22 @@
+# <%= title %> Extension For Quarto
+
+_TODO_: Add a short description of your extension.
+
+## Installing
+
+_TODO_: Replace the `<github-organization>` with your GitHub organization.
+
+```bash
+quarto add <github-organization>/<%= filesafename %>
+```
+
+This will install the extension under the `_extensions` subdirectory.
+If you're using version control, you will want to check in this directory.
+
+## Using
+
+This extension installs a [brand.yml](https://posit-dev.github.io/brand-yml/) configuration for _your organization name_.
+
+## Example
+
+Here is the source code for a minimal example: [example.qmd](example.qmd).

src/resources/create/extensions/brand/_extensions/qstart-filesafename-qend/_extension.ejs.yml

@@ -0,0 +1,8 @@
+title: <%= title %>
+author: <%= author %>
+version: <%= version %>
+quarto-required: ">=<%= quartoversion %>"
+contributes:
+  metadata:
+    project:
+      brand: brand.yml

src/resources/create/extensions/brand/_extensions/qstart-filesafename-qend/brand.yml

@@ -0,0 +1,9 @@
+# minimal brand.yml enabling dark mode
+# replace with your brand colors, logos, and typography!
+color:
+  background:
+    light: "#fff"
+    dark: "#000"
+  foreground:
+    light: "#000"
+    dark: "#fff"

src/resources/create/extensions/brand/example.qmd

@@ -0,0 +1,26 @@
+---
+title: your brand extension
+---
+
+# brand.yml extension
+
+Here is some inline code: `def foo(x): return x`{.python} and `y`{.python} and `z`{.python}.
+
+Here is [a link](https://example.com).
+
+Here is a code block:
+
+```{.r}
+# | echo: true
+fibonacci <- function(n) {
+  if (n <= 0) {
+    return(NULL)
+  } else if (n == 1) {
+    return(0)
+  } else if (n == 2) {
+    return(1)
+  } else {
+    return(fibonacci(n - 1) + fibonacci(n - 2))
+  }
+}
+```

src/resources/schema/project.yml

@@ -32,6 +32,13 @@
           maybeArrayOf:
             schema: path
             description: "Additional file resources to be copied to output directory"
+        brand:
+          schema:
+            ref: brand-path-bool-light-dark
+          description: |
+            Branding information to use for this document. If a string, the path to a brand file.
+            If false, don't use branding on this document. If an object, an inline brand
+            definition, or an object with light and dark brand paths or definitions.
         preview:
           description: Options for `quarto preview`
           schema: