unified brand, dark logo, etc

[gordonwoodhull]

@cwickham

This is not 100% complete so feel to wait on reviewing this. I'll put as draft until I've given it another pass and reviewed PRs to figure out what I've missed.

However, it does include all the big changes

• unified brand (with light and dark colors) is preferred over light and dark brands
• brand-mode
• removed some limitations and added others (but they are smaller)
• document logo can have light/dark variants (and also mention overriding with path)
• typst logo special options moved to the main typst page (introduced with brand, but can be used without it)

So I thought it was worth opening a PR now!

I feel like the new page.typ partial should be documented somewhere, but we do not copy or document some of the other Typst partials, so I'm not sure if it belongs here:

https://quarto.org/docs/output-formats/typst-custom.html

The docs list 2 but there are now 7:

biblio.typ		page.typ		typst-template.typ
definitions.typ		template.typ
notes.typ		typst-show.typ

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1779.quarto.org

🔄 Modified Documents

• docs/authoring/brand.qmd
• docs/extensions/metadata.qmd
• docs/output-formats/typst.qmd

[cwickham]

I'll take a good look early next week.

In terms of the partials: I think we should document page.typ at https://quarto.org/docs/journals/templates.html#typst-partials.

If feels like page.typ is much more similar to tyspt-show.typ and typst-template.typ than notes.typ, definitions.typ or biblio.typ, in that you likely want to change it if you are customizing Typst output. I wonder if it should be added to the template you get with quarto create extension format typst, we update the other partials in that template, and then re-write the https://quarto.org/docs/output-formats/typst-custom.html#create-a-format section.

Side question: do the templates we list in https://quarto.org/docs/output-formats/typst-custom.html#custom-formats work in 1.8?

[gordonwoodhull]

Sounds good. I'll document page.typ with the Typst partials for now. We can decide whether to put it in create extension format typst later. (Glad to do it, have more urgent things to fix for Monday's patch release.)

Sadly, 5/6 of the custom typst formats are not working - only letter still works. Typst had some breaking changes in 0.13, with deprecation messages appearing in 0.12 - but we never bundled that version in our stable releases, so nobody saw the messages.

We discovered this preparing for conf, but it's been broken since 1.7.

It's not hard to fix them, but we might also consider whether to update them, since most of them have continued to be developed since we forked them.

[cwickham]

I've taken a look at what is here so far and it looks great - just a couple of minor suggestions.

Two things:

• Can you edit _quarto.yml to put /docs/extensions/brand.qmd in the Extensions sidebar nav?
• Should we mention the existence of the brand type of extension somewhere on this page? Ideally, I think this page might have a section on "Sharing brand across projects", but maybe there's a lot of work in flux that will dictate exactly what we say in it (and how much we can link out to more general brand docs).

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1779.quarto.org

🔄 Modified Documents

• docs/authoring/brand.qmd
• docs/extensions/metadata.qmd
• docs/output-formats/typst.qmd

[gordonwoodhull]

I think we should add the “sharing a brand” section, link to the quarto brand extension, and mention that we will have quarto use brand in 1.9.

This could even link to the same section in the prerelease docs. “Watch this space.”

We are sure quarto use brand is possible and we will implement it. We won’t know all the details until we do.

[gordonwoodhull]

Can you edit _quarto.yml to put /docs/extensions/brand.qmd in the Extensions sidebar nav?

While doing this, I noticed that "Starter Templates" was out of order in the sidebar w.r.t. the text on docs/extensions/creating.qmd, so I've made the sidebar consistent with the text. Please check.

authoring/brand.qmd

I've added a section "sharing brands across projects". It would be nice to point to the "This is the Quarto Way" page @cscheid has discussed, to explain why Quarto projects must live in a single directory tree. The callout describes the limitation, but it does not say why this is so.

(I know that pointing to the prerelease docs is an uncommon move and will require future maintenance, as well as updating this page in prerelease with "watch this space" instead of the link. I think that quarto use brand is important enough to warrant the hassle. But I'm glad to take this out if others think this is a bad idea!)

I found that I disagreed slightly with the theme compatibility section at the end of the brand authoring page. So I changed the heading and text somewhat. I don't think we expect everyone to migrate to brand.yml from themes. Themes are more powerful; themes are still fully supported; and combining brands with themes will be supported in perpetuity.

I think this is ready to merge; will do one last check to make sure I haven't missed anything.

Edit: found new brand-logo and brand-logo-images for Typst; adding to the "using _brand.yml values" section.

• #typst: declare brand-logo and brand-logo-images dictionaries quarto-cli#13119

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1779.quarto.org

🔄 Modified Documents

• docs/authoring/brand.qmd
• docs/extensions/metadata.qmd
• docs/journals/templates.qmd
• docs/output-formats/typst.qmd

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1779.quarto.org

🔄 Modified Documents

• docs/authoring/brand.qmd
• docs/extensions/metadata.qmd
• docs/journals/templates.qmd
• docs/output-formats/typst.qmd

[cscheid]

@gordonwoodhull FYI, https://github.com/quarto-dev/design-principles cf our meeting

[cwickham]

LGTM!

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1779.quarto.org

🔄 Modified Documents

• docs/authoring/brand.qmd
• docs/extensions/metadata.qmd
• docs/journals/templates.qmd
• docs/output-formats/typst.qmd

[github-actions]

Successfully created backport PR for prerelease:

• [Sync to prerelease] unified brand, dark logo, etc #1785