docs: update mkdocs generation to include OpenGraph meta tags

[setchy]

Tell us more.

Update the mkdocs generation process/templates to include Open Graph meta tags.

This will make any Renovate documentation links shared on socials / Slack etc rich

[secustor]

🤷 why not.

I think there isn't a clear need, but also no downside for it.

[secustor]

@rarkins might be interested in this from a marketing perspective

[HonkingGoose]

Material for MkDocs can create social cards for us

Material for MkDocs has a built-in plugin called social that can make nice social cards for links. Read the docs to learn how to set that up:

• Material for MkDocs, Setting up social cards

Insiders build needed to customize the cards

If we're happy with the default cards that Material for MkDocs gives us, we don't need to do anything more. 😄

But if we want to customize the cards, we need to use the Insiders version. We're paying for Insiders already, just to sponsor the project. But we're not using the Insiders build.

I already asked for help on how best to setup Insiders for us. The key pain point is that the Insiders build must be kept secret. That makes things like generating a preview locally hard to do for those not explictly given access to the "Renovate Material for MkDocs Insiders fork".

• How to get started with Insiders? For the Renovate docs site. squidfunk/mkdocs-material#6585

[rarkins]

@HonkingGoose could you describe more about "generating a preview locally". Do you mean you clone the repo, check out a PR, run a docs build, then load the results in a browser?

[HonkingGoose]

Do you mean you clone the repo, check out a PR, run a docs build, then load the results in a browser?

Yes, that's the bit I'm worried about when we start using the Insiders build.

Material for MkDocs behavior

The philosophy for Material for MkDocs is:

• All users can run a build.
• All users can configure Insiders features, by reading the docs, and double-checking.
• All users can load a preview in the browser.

But:

• Users who can clone the Insiders fork can make a preview, and see all the Insiders features in action.
• But users who clone from the normal Renovate repository will only see the basic features in their preview.

Summary

Type of user	Make a build?	Source files for build	See the "real" preview?
Insider	Yes, full build	Insiders fork repo	Yes
Outsider	Yes, but only a partial build	Renovate repo	No

What does this all mean for us?

Say we get everything configured properly. Here's how I imagine the best workflow:

1. Everyone can make a normal docs build via the renovatebot/renovate repository, and see the basic features in their browser preview.
2. Everybody can configure Insiders-only features, by reading the docs.
3. But only those with access to the Insiders-fork can see the full preview in their browser (at least locally!).
4. The Renovate repository has a build step that pulls in the special bits from the Insider fork, and makes the published docs.
5. A bot comments with a "preview link" based on the full-fat Insiders build. So we can easily check if the new content will work on the published site. (This may be difficult due to rate limits, due to all the content we pull in on a real docs build!). I know Netlify and Vercel offer a feature like this.

I already asked for help

I'm struggling to figure out how we should go about configuring, and using our Insiders fork. So I asked for help:

• How to get started with Insiders? For the Renovate docs site. squidfunk/mkdocs-material#6585

I'm a bit sad we're paying for the Insiders features, but do not have a way to use the Insiders features, yet.

[rarkins]

I was initially happy just to support the project we use, but if the project fundamentally can't support another open source project using the insiders build, we maybe should discontinue our sponsorship (because we'll never be able to use it).