Modern sites like to provide something with a bit more bling than just a text URL when linking to external pages. Instead, the targetted site can provide some text and graphics that should be displayed in a box that represents the link. Since the Administrator's Guide will likely be linked to (e.g. to reference settings), we should make sure this works, so we have pretty links. The easiest way is probably to add the Open Graph metadata to each page: https://ogp.me/ As an example of a consumer of this data, we don't have to look further than our own community site.
There's at least one Sphinx extension for convenient handling: https://github.com/wpilibsuite/sphinxext-opengraph
One problematic limitation is that URLs cannot be relative. That means if a user hosts their own copy of the documentation, then it will be difficult to make sure images and such are also grabbed from the user's servers. We'll likely have to host such resources on our web server for all instances of the documentation.
Created attachment 1253 [details] Discourse preview with just a title and meta description tag After adding meta descriptions as part of bug 8318, at least Slack Discourse and shows a fancy link preview containing the page title and meta description. I'm not sure if this is the general case or just happens specifically for slack.
I really mangled the grammar in comment 3. What I meant to say is that we get very reasonable previews in both Slack and Discourse now. This probably gives lower priority to this issue.
