Im a bit reluctant to use an unofficial fork - do we absolutely need it? Dont we replace the fonts anyway?

The convenience with the official project is that there is a free site we can use without needing to mess with yarn - this makes it a lot more accessible.

The official version doesn't allow custom fonts at all. That means you can't see an accurate representation of what you're working on while you're working on it.

All the fonts are also variable width so there will definitely be significant differences if we swap a font with a different font, especially given that the official version's default "Virgil" is a very wide font. When we set the font URL in the SVG we're actually undoing the swap-to-defaults that the SVG export performs.

Looking at the SVGs that you recently created, which I assume came from the official hosted app, they have one font referenced:

There's no indication that the embedded font there is actually "Virgil".

I've just done a quick test now at excalidraw.com: added text in one of each of their 3 fonts, then exported to SVG. The file contains an embedded "Excalifont", 5 embedded copies of "Nunito", and "Comic Shanns" (which is supposed to be their code font but looks not at all code-like). Until now their fonts have always been Virgil (now rebranded to Excalifont), Cascadia, and Assistant.

So problem is really the opposite, where using the hosted app means they can change things on a whim and and offer no guarantees of backward compatibility. The fork doesn't have any issues - all the functionality works - and can always pin a version if necessary. I don't think there will be any new features in the official version that we will be yearning for - the app does what's needed.

I understand the layout can differ but is it really that important?

I generally prefer things that take least effort for the person developing the doc and leave more of the look and feel to the site builder scripts - that way there can be less variability and the user only needs to think about what to write not how to lay the text out. In other words it does not matter if the text is slightly bigger or smaller as long as the bounding box is set over the correct region.

If the bounding box is configured with extra room for text expansion that partly mitigates the problem. That is IF the user constantly remembers to do this for every bounding box.

Even so there are situations where it doesn't work:

1. If text is left-aligned but manually positioned to be centered under another object, then the font changes size and the text extended to the right and possibly even wraps. It leaves an unbalanced result that wasn't the author's intention.
   

2. If the text is associated with an object on it's right and the text is not set to right-align, then swapping can cause it to overlap the object on the right or shrink away for the object leaving a big gap. So that means every time you have text associated with something on it's right you have to remember to make the text right aligned and extend the bounding box to the left.
   

Keeping all these possibilities in mind sounds like much more effort to me. I never have to worry about whether the bounding boxes will be sufficient or if I've left some text left-aligned when it properly should be right-aligned. WYSIWYG is really really important.

I like the idea of a consistent font everywhere - lets just coerce it with a presubmit - that way this docs are not relevant

We have to do the font link substitution regardless of how we do it. We swap the links to keep the fonts the same.

In the app you have to configure the fonts so that you can see them while you are drawing. As I mentioned in another comment the various fonts are variable width so a blind swap will cause unexpected shifts in their positioning

Yeah the font will be repositioned within the bounding box - but as long as the bounding box is reasonable it should flow within it.

Just tried it and it makes no practical difference to the font positioning:

Original font

Replaced with our font

I lean towards just making the instructions simpler. If a power user really wants to use the exact same font - go for it. But we dont need to mandate that in this style guide.

The instructions are not going to be simpler if you have to explain that the user should imagine different fonts while drawing, other than the ones their eyes are seeing.

I've done this test with Excalidraw (the official version) and the bounding box resizes vertically and wraps the text. So that would require us to always add extra space to the bounding box so that it doesn't change size with the font swap. And then also try to explain why that's necessary and provide some estimation of how much extra space is sufficient.

I would really like to use the official version (although not their hosted app which changes without notice) but they don't support custom fonts and their default fonts suck. If you read their issues board it's frustration that a lot of people have. They've added a font picker which hints at custom font becoming possible in future, but not yet: excalidraw/excalidraw#8012

The official version is currently doing this with the SVG exports:

• allowing 4 default fonts (3 GUI presets + 1 extra)
• embedding them multiple times

We could swap a 4-font definitions section and map to those font names but what if they decide to add more or change the names of the existing ones? They're done that in the past (where "Virgil" became "Excalifont") and the change I linked to above suggests that the font aspect is currently very much in flux and undecided.

This section should just say - fonts are normalized to the standard fonts used throughout the site so dont worry about specific fonts in your drawings.

The technical details are not relevant and could change in future - also not really actionable by readers.

Sure once we've settled on a process that works and the specifics of that comes down to these choices:

1. Use Excalidraw.com hosted app. Use their fonts, use carefully designed bounding boxes and alignments, and accept that quite often the SVGs could be significantly messed up after the font swap, something which we'll only know about once the images have been published to the docs site. Also expect breakages without warning as the online app evolves.

2. Use a locally installed instance of the official Excalidraw. That eliminates the unexpected breakages but otherwise has all the same downsides as the 1st option.

3. Use a locally installed version of the excalidraw-zh fork, which allows WYSIWYG editing and generates SVGs with a 1-to-1 font spec that can be swapped without unexpected consequences. It provides all the desired functionality that the official version offers, or even promises to offer in future. It's works and it's not going to suddenly break.

No problem - it is actually not that bad because usually when writing docs we have to run hugo anyway so the font substitution happens in real time and you can see updates to the svg immediately.

Ok, we still need to pick one though because they all embed different font names in the vector part and we just want to replace the font definition part to achieve the right mapping.

Just added a commit that shows the font defs swap we need to make when exporting SVG from excalidraw.com