feat: Dynamic og image #1344

[vasfvitor]

Continuing from #1608

OUTDATED: ~~Still working on it. But thinking whether we should consider https://github.com/delucis/astro-og-canvas or another implementation. Current PR is based on: https://github.com/JonasKruckenberg/JonasKruckenberg/blob/main/src/pages/social-image/[...path].png.ts~~

Files: astro.config.mjs - Added Head component override; Updated Footer override reference; removed head meta tags

~~templates.ts - receives the frontmatter data to build SVG that will be processed by Sharp. Currently it's all done inline.~~

~~utils.ts - helper functions~~

~~[...path].png.ts - Astro dynamic routes mixed with social-image generation via Sharp. It has to be in /pages~~

~~Reference:~~ ~~https://docs.astro.build/en/core-concepts/endpoints/#static-file-endpoints~~ ~~https://docs.astro.build/en/core-concepts/routing/#dynamic-routes~~

~~tsconfig.json - import alias to /assets where the .ts files are~~

~~Issue:~~ ~~Locally the font (SF-Pro) is working, but still need to check how live/preview build will behave. Sharp can't process embedded fonts in SVG. So the current implementation has SVG importing a font file. But Sharp apparently needs the font to be installed in the system (by default, SF-Pro will not be on netlify and possible any other font will), so maybe we'll need fonts.conf file.~~

[netlify[bot]]

✅ Deploy Preview for tauri-v2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	050fa32aa7c5fe2ba000fa19e53f12871f263cdc
🔍 Latest deploy log	https://app.netlify.com/sites/tauri-v2/deploys/669291acf290f00008a1f6fc
😎 Deploy Preview	https://deploy-preview-1616--tauri-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (🟢 up 1 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[vasfvitor]

PR deploy time: 2m 46s

Current deploy time: 1m 52s

54s increase in deploy time

[vasfvitor]

[update in the next comment]

Original design:

Local preview:

Netlify preview:

~~Three~~ ~~Two issues:~~ ~~(1) The font and~~ ~~(2) date are wrong on Netlify preview.~~ (3) ~~Text's left side margin does not match original design. Plus the grid isn't in the same position. It seems that the svg shifter left.~~

(3) fixed (2) there wasn't a problem after all, the post actual date is 2023-05-03 and live/preview is ok. Only locally is different, no problem :D (1) fixed

I need input if I could continue to work on this.

Thanks

[vasfvitor]

[update] local: preview:

[lorenzolewis]

I did a little bit of thinking on this one this afternoon (first chance I've had to sit down with it, so apologies for the delay). There's 2 options that come to mind: 1) Continue with this down the current implementation route or 2) Look at building something that could be included upstream in Starlight.

Current Implantation

As you've already put in the work to set this up then we could continue with the current approach, but in the future I'd prefer to use any official Astro/Starlight solution if one is created.

If you'd like to continue then I'd make the following changes:

1. Switch from using the SF font to instead using the fonts defined in https://github.com/withastro/starlight/blob/f9f96c88c8963b0d1aed58169181bbc992a3e03d/packages/starlight/style/props.css#L85
2. I don't believe we need anything new added in public as all resources will be generated during build, right?
3. Similar to below, instead of using import.meta.glob use getCollection() to pull in the various pages.

There's some smaller nit-picks I can do in a proper code review but will save that based on which path you'd prefer.

Starlight plugin

I know this is something that upstream would appreciate via a Starlight plugin (https://discord.com/channels/830184174198718474/1070481941863878697/1166734878201610342). If that's the approach you'd like to take then I think it would make sense to use Delucis 's https://github.com/delucis/astro-og-canvas implementation with a few tweaks. One gap that I see right now is that it doesn't support custom backgrounds but I'm sure that's something he's be open to accepting via a PR.

To make that a proper integration I would...

1. Create an Astro integration to inject the image route via https://docs.astro.build/en/reference/integrations-reference/#injectroute-option
2. Instead of using import.meta.glob, use getCollection() to pull in the various pages. There may be a Starlight-specific version of this function that takes in account the fallback pages generated for non-default locales.
3. Create some sensible defaults for the image using https://starlight.astro.build/reference/configuration/#title-required, https://starlight.astro.build/reference/configuration/#description, https://starlight.astro.build/reference/configuration/#logo, etc.
4. Create a component override for Head.astro to add in the respective OG image paths (but still pulling in any of the values defined in https://starlight.astro.build/reference/configuration/#head)

That's a lot of extra steps but we could start with some of them here as a POC before looking at making a proper Astro integration.

---

Ultimately the route is up to you and I'm happy to continue down whichever you prefer keeping in mind the notes above. Again, apologies for the delay and thanks so much for putting this in!

[vasfvitor]

It's all fine, I'm glad to see you around again :D

--//-- OUTDATED because we are utilizing astro-og-canvas, it's better as it cache images --//-- Today I've made a few build time test with astro-og-canvas, nothing conclusive, plus I've added a way to use background image (no svg yet). I'll play some more before getting feedback on it.

Addressing your comment

About Current Implantation:

• [x] 1. Change fonts.
• [ ] 2. Yes, currently only the font file and fontconfig are in public, I believe it could be moved into another folder. I'd say a specific font is needed to maintain consistency between dev/prod preview. Not to worry right now.
• [x] 3. Utilize getCollection().

About Starlight plugin:

There's an open discussion about Starlight plugins and from what I glanced there's not much that would add to this issue. It would still be an Astro integration after all.

• [ ] 1. Create integration to leverage injectRoute
• [ ] 2. Utilize getCollection() and take in account fallback pages.
• [ ] 3. Sensible defaults for title, description and logo.
• [ ] 4. Override head but keep custom settings.

Finally, I'll do some more research and see where it leads to before making a decision. Checklist is just to get an overview. So far I'm inclined to improve upon Delucis 's astro-og-canvas. I'm down to contributing to Astro's ecosystem.

Thank you for you attention and directions. If you have anything else to add, I'm all ears.

[lorenzolewis]

Thank you! I've also asked the question over on Astro's discord in https://discord.com/channels/830184174198718474/1171038039276015656 that might be useful to follow along if you decide to dig further into the integration route.

[vasfvitor]

quick updates: I'm working on background for astro-og-canvas. Btw, that caching feat Delucis implemented is genius.

TODO (non-exhaustive)

• [x] tweak astro-og-canvas to add post date field.
• [x] implement locally into tauri-docs/next (WIP)
• [ ] Create a component override for Head.astro to add in the respective OG image paths (but still pulling in any of the values defined in config

Lastly, I think the TAURI logo should be separated from the background, this would allow it to switch sides in case of RTL locale by astro-og-canvas. But It could be implemented later.

edit: https://github.com/withastro/astro/issues/8972 issue when building, related to getCollection(), alternative is to go back to import.glob, I guess

[lorenzolewis]

@vasfvitor I haven't been keeping too up to date on OG images here nor on the Astro side of things. Was there anything you'd like my input on for this?

[vasfvitor]

@lorenzolewis to get you up to date:

There's an open issue over og-canvas to add background option but it still to be resolved.

Locally I have a version that produce more or less the figma model, minor difference is that the text is top aligned. It was done in a modified version of og-canvas. Images attached.

But still can't build, I haven't figured out how in Astro works, but Starlight don't (see the mentioned issue in my previous reply). I was/am expecting to see (if) how it's implement on the new Astro Docs in Starlight, so far og-canvas is removed in the migration pr.

The input I need is: If we want this soon just call it and I'll start to work.

note: Idk how exactly, either with html post processing with the astro:build:done hook in the integration or utilize import.glob to place the corresponding og metatags in the <head> The issue is in the head override component. I'll have to play around. If you have any suggestion.

blog-post-with-date: one-line two-lines still have to add i18n pages and config rtl and ltr options, but here is a preview

[lorenzolewis]

Thanks for the update! If you're alright with it then I think this is something that can wait a bit so we can see how upstream implements it and see if that's the approach we'd like to follow. There's plenty of other things to work on with migration PRs in the meantime to keep us busy :)

[vasfvitor]

I fully agree

[vasfvitor]

quick update: Astro Docs migration to Starlight is done (yaaay!) and they've found a interesting workaround to implement og-canvas. Actually, I've already ~copied~ yoinked their implementation a few days ago and it worked. But there's still work to be done.

plus, og-canvas now supports background images. \o/

I'll get back to it later

note to self:

Astro Docs migration commits: https://www.github.com/withastro/docs/pull/4266/commits

their OG implementation: https://www.github.com/withastro/docs/pull/4266/commits/01fba2006b281ec970c528abbebfd0e50e8acb45

00 hack to make it work: https://www.github.com/withastro/docs/pull/4266/commits/030073f32d6dfe586c6e1da8d48d6b5485541ba2

use background image: https://www.github.com/withastro/docs/pull/4266/commits/3e6bb9a86d5560f328628e23ff71c717e2396150

remember to check if they changed anything in the implementation

update: test import {mergeHead} from 'node_modules/@astrojs/starlight/utils/head';

[socket-security[bot]]

New dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher

View full report↗︎

[vasfvitor]

this is mostly ready, already updated it to use og-canvas but I need to get around lines width and font size so content fits nicely, more os less like the Figma mocks.

For now font is Noto Sans because the defaults weren't rendering zh-CN chars (at least locally) so to avoid this I think it's better we ship a default font and a fallback to other languages that needs it. What do you think? I see the Figma files are using Inter now

I couldn't find way to merge heads from Starlight config into override. Oh, and the font size is bigger when there's no description and smaller on blog posts

This is a preview of not so random pages https://deploy-preview-1616--tauri-docs-starlight.netlify.app/open-graph/preview/

[lorenzolewis]

Looking at the commends extraField and respective pnpm patch is only needed in order to render the blog date, right? If that's the case then I'd prefer dropping the except and using the date in that place I think. As soon as we throw in patches then it makes updating deps much much more difficult (the only reason I have one for typedoc-plugin-markdown is because it was in pre-release and didn't have some upstream fixes yet).

For the font does it work to use Inter as the default and then Noto Sans as a fallback (as Inter is what we use for any design-related things in Tauri)? Is it also possible to rely on https://fontsource.org for Inter and Noto Sans instead of having the files directly? That makes any licensing much clearer as it's documented in the dependency.

In the above image there seems to be an extra space between the heading text and the .... I'm assuming this is just because it happened to fall there so trimming the text of any whitespace before appending the ... should clean that right up.

I'm going to put a few extra design critiques below but I think outside of the above it looks good to me outside of a bit of cleanup and documentation here and there.

Design feedback:

• Can the descriptions take up to 3 lines before they're truncated? This may only be for the blog format which could be redundant based on the feedback above.
• Right now the text seems to be aligned to the top of the image. Could it be vertically centre aligned to the image so it's a bit closer to the Figma mocks? The idea would be to have similar padding from the top and bottom edges to the content.

[vasfvitor]

Looking at the commends extraField and respective pnpm patch is only needed in order to render the blog date, right?

One patch is for the blog date. There's another patch to place the logo at the bottom right https://github.com/tauri-apps/tauri-docs/pull/1616/commits/f574e70eccab35b1a9bb7e7a1d5a962838dce924 I can open a feature request upstream to customize the logo corner position, then we'd have no patches

For the font does it work to use Inter as the default and then Noto Sans as a fallback

Yes, I'll do it.

Is it also possible to rely on https://fontsource.org/ for Inter and Noto Sans instead of having the files directly? That makes any licensing much clearer as it's documented in the dependency

Yeah, I guess that should be possible

In the above image there seems to be an extra space between the heading text and the ...

Nice catch, can't believe I missed that.

Can the descriptions take up to 3 lines before they're truncated? This may only be for the blog format which could be redundant based on the feedback above.

It's possible, I'll have to see how it fits, I guess the only way I tried was without truncation and that got over the logo. Btw, how about line heights? Is there a default and/or recommended values?

Right now the text seems to be aligned to the top of the image. Could it be vertically centre aligned to the image so it's a bit closer to the Figma mocks

As of now padding is equal in every side, another possible feature request. And I think both this (allow block and inline padding?) and logo corner position would be nice features. One hacky thing that could be done is place "\n" before the title, but it doesn't actually center

[lorenzolewis]

If we just go with the default layouts, number of lines, etc. with no patches, what do we get? Logo in the top? What is the default behaviour for number of lines on title and description? If astro-og-canvas is the most straight-forward thing to use then maybe we can use what it already has and then PR the work you've already done upstream (such as alignment for the logo)? I'm not 100% sure how customisable of an API Chris (author) wants to support on that but can always see.

[vasfvitor]

Yeah astro-og-canvas with the cache strategy is the best we have I'd say.

Yes, logo on left corner (right for rtl). There's no default lines number, I created a clamp function and was fiddling with it to make it fit 1 or 2 lines based on font size, not fully ready yet.

In those previews below, text may see misaligned from image to image because when it's blog, title and excerpt font is 75% of base size. Same when there's description, it's 85%.

I hope this images help you visualize.

This is a local preview without patch, but lines limited

No lines limit

Slightly increased padding, reduced logo size and constant font size (notice that the text changes it's vertical position):

Overall they may look off when looked side by side but I think that's can be misleading as we won't ever see them like this, one change of seeing two or more in a column when pasting multiple links

[lorenzolewis]

From a maintenance perspective I like these options more. Could we go with the larger logo (second image) and the constant font sizes (last image)? I think if we can go with that and then trimming any characters over 2 lines (for both the title and summary) then that should be the sweet spot I'm thinking.

[vasfvitor]

you can preview the last changes here: https://deploy-preview-1616--tauri-docs-starlight.netlify.app/open-graph/preview/ ~~and for a unknown reason the Noto Sans font isn't loading (I guess Inter is, I can't id it visually without comparing), neither locally (tried loading all the 100's woff files). I'll prolly end up using the fontsource api url instead of the dependency 'https://api.fontsource.org/v1/fonts/noto-sans-sc/chinese-simplified-400-normal.ttf'~~

nvm, got it :D

-- Before merging we need to remove the preview.astro page and setup the env var so preview builds don't generate og images.

[lorenzolewis]

Yeah, I think this has a better balance for maintainability and the info we want. Is this still around a 54s increase in build time? Do you think the caching changes in Astro v4 would help us out here? We haven't updated because of the blog integration yet.

[vasfvitor]

I'll revisit this soon because the head override will have to include the recent head changes someway, or find a way to inject the og metatags into the head without overriding it. This was expected and at the time I gave a shot at it but failed

well... it can be as simple as just copying the contents tho... not sure... I'll look again