Typst Brand Logo: Thoughts on Placement

[christopherkenny]

Description

I was teaching a Quarto workshop yesterday. One of the demos was using an implementation of Princeton's brand guidelines for generic PDFs (with format: typst).

By default, it looks a little silly, due to the size of the logo:

That's fine, as it can be configured by setting width: 2em or otherwise.

This is currently set in the page partial:

$if(logo)$
#set page(background: align($logo.location$, box(inset: $logo.inset$, image("$logo.path$", width: $logo.width$$if(logo.alt)$, alt: "$logo.alt$"$endif$))))
$endif$

Note that I can't figure out how to edit location or inset, while each of path, alt, and width can be set.

For example this:

---
title: "Untitled"
format:
  typst:
    keep-typ: true
logo:
  path: assets/PU_mark.png
  location: bottom + right
  width: 2em
  inset: 1in
  alt: "princeton shield"
---

{{< lipsum 9 >}}

Creates this line:

#set page(background: align(left+top, box(inset: 0.75in, image("assets/PU_mark.png", width: 2em, alt: "princeton shield"))))

This gives me three related questions:

• Is location intended to be hard-coded? If so, then the choice of background seems odd. Namely, if it's intended to be in the top left, then it would make sense to use header: instead. Then, rather than setting a width, a reasonable default height: 90% could be set, which would auto scale any logos to the heading margin and the size could be adjusted by rescaling the height parameter.

• If not, would it be possible to make inset configurable and consider still using height rather than (or in conjunction with) width? This makes it easier to align margins as setting things like: 1.5 margin and 0.5 inset => I have 1.0 of space left in the margin for my logo.

• Again, if not, I can see why you might want to configure width if you want a side logo, by setting e.g. location: horizon + left and a similar math of 1.0 margin - 0.5 inset => 0.5 for a logo.

Given how the brand is currently implemented, I would think that either something is being accidentally gobbled up during processing or this is intended as a header rather than the background.

If a height parameter is added, then width: auto would make for a good default that doesn't stretch logos, so that they can be resized without distorting relative proportions.

As one last related thought from working with this, it might also make sense to generalize with logo.type: which could be background, header, or footer, which would allow for both sensible defaults (e.g., type: header, height: 90%, location: horizon + left) which will place it very close to where it is, but with a bit of space above and below + auto resize to different margins. Then if someone wants a background or footer, it can be specified. Notably, this can also avoid eating up control over the background, if you want to be able to do things like set page(background: rotate(45deg, text(128pt, fill: rgb("80000033"))[*DRAFT*]) while also having a logo.

Sorry for dumping so many comments at once, just sharing my thought process of what I would have expected the behavior to be and what I think more a general behavior could be without sacrificing control.

[gordonwoodhull]

I’d be happy to consider proposals for the defaults. I admit I didn’t think any one default would work, so I made Typst logo positioning (almost) completely customizable.

The settings use css conventions (even though they are currently only for Typst) and they are documented here

https://quarto.org/docs/output-formats/typst.html#logo-position

I moved this section in the last release because what it documents isn't really a brand.yml feature for Typst; it’s a more complex Typst feature which happens to support brand.

In particular, I think width worked for you? I see 2em in your output. Any css units that are convertible to Typst units are valid here.

But you need padding instead of inset, and location uses dashes instead of plus, css alignment names, and it might not like spaces.

It would be good to warn if these are misused!

Please let me know if you have any trouble with the logo positioning options, or suggestions. I think they were not too discoverable and have been underused.

I considered allowing inset but it would probably have to be inset-typst or something like that, since we’re all in on CSS as our lingua franca for the foreseeable future. (Not that we won’t be happy if Typst wins the web someday!)

I like the idea of allowing height instead of width or in addition. I didn’t get around to it at the time but I think it’s not hard to do.

I also like the idea for different places for the logo. Background seemed more general to me, like a watermark, but I’d consider a PR if you see a way to make this more general. I’m not sure about the key type; maybe parent or placement?

[gordonwoodhull]

Also, I think changing the placement/parent is already possible in an extension targeting page.typ, but I haven’t tried it.

page.typ isn’t copied in when you quarto create extension format and select Typst, but we’re considering adding it. and it should work to just copy it in and modify it.

Lmk if you try it and it doesn’t work!

[christopherkenny]

Thank you for the response. I had missed that logo options were documented in the general page, instead of the logo, so I didn't see that it wanted - instead of +. After setting that, I see the configurability. Sorry about that, my major confusions are my fault here. (I agree it would be nice to have it warn when misused, as my default response was to fidget with align properties like "horizon" rather than "middle".)

I can make a PR for support of $logo.parent$ (or .placement if preferred) and for $logo.height$.

I think the parent/placement bit is very helpful with a configuration like:

$if(logo)$
#set page($logo.parent$: align($logo.location$, box(inset: $logo.inset$, image("$logo.path$", width: $logo.width$$if(logo.alt)$, alt: "$logo.alt$"$endif$))))
$endif$

Since then you can really target the header and make it explicit that you're not overlapping with text. I agree background makes sense when non-configurable, as it lets you mimic headers and footers.

page.typ isn’t copied in when you quarto create extension format and select Typst, but we’re considering adding it. and it should work to just copy it in and modify it.

For what it's worth, I normally just open the subdirectory with the partials anyway to get copies of the non-default partials.