Conversation
|
Comparing the two cards shown, I prefer the one generated by the mkdocs plugin for a few reasons:
That said, I like that the PR uses a pre-generated image. How difficult would it be for a simple script to generate card images for each of the pages, more closely matching what the mkdocs plugin generates, but still check-in those images once rather than needing to have cairo installed to generate them every time the docs are built? |
|
I don't really mind sticking with the same image used in the playground, especially in a first draft. When I looked at this previously, I was more concerned about a few missing ruff/playground/ruff/index.html Lines 18 to 26 in 77637e8 Compared to the playground header, we have an extra I definitely prefer not adding another mkdocs plugin, especially in case we end up moving away from mkdocs. |
3 participants
Summary
Closes #8542.
This PR aims to make ruff's documentation sharing appear as a card on social medias via adding OpenGraph(OG) tags in the
<head>section of the documentation.Implementation
The og tags were added to
docs/.override/main.html, and the image added is taken fromplayground/ruff/public/Ruff.png. The image was chosen since it fits the card better compared to using just the logo.How it looks with the changes implemented (images from https://www.opengraph.xyz/)
How it looks if a specific page is shown
The card should also display the correct title, depending on the page that was shared.
Test Plan
The testing are mainly done on site such as https://www.opengraph.xyz/, with ngrok as a proxy to expose the local changes
Alternative implementation
There's a
mkdocs-materialsocial plugin that supports generating beautiful cards for each pages, which results in something like so:More details for the plugin can be seen here: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards.
The plugin relies on extra dependencies for generating image:
CairoSVGandpillow, and will require installation of native dependencies (details: https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/). When setting this up I do have some issues withuvxnot detectingDYLD_FALLBACK_LIBRARY_PATH, but running it in the venv withoutuvxresolves this.I went with the current approach instead of this alternative ones since I'm already done with the current approach by the time I found the social plugin.
Personally I do think the social plugin looks better in general, but would like some opinion on this matter: which will be the preferred implementation for ruff here?