canonical / canonical/sphinx-stack
ogp_site_url example structure breaks if applied to versioned docs
- Dominant language
- No language data
- Stars
- 37
- Forks
- 77
- Avg merge
- 8d 13h
- Merged PRs (30d)
- 5
Description
In [conf.py](https://github.com/canonical/sphinx-docs-starter-pack/blob/main/docs/conf.py#L73), the starter pack gives this example for setting `ogp_site_url`:
```python
ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/"
```
When versioned docs follow this pattern, it creates a broken URL. For example, https://documentation.ubuntu.com/chisel follows the provided pattern and sets it like this:
```python
ogp_site_url = "https://documentation.ubuntu.com/chisel/"
```
Here's how that renders in HTML for one of the pages, for example:
```html
```
This is a broken link. The correct URL would include the version, like this:
```html
```
One way to address this would be to include the version, like this:
```python
ogp_site_url = "https://documentation.ubuntu.com/chisel/en/latest"
```
However, this means that you have to set this differently for each version of the docs. Better to do this: elsewhere in `conf.py`, the `html_baseurl` should already be set like this:
```python
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
```
This is set near the sitemap settings in the starter pack at present, but it doesn't necessarily need to be. I suggest moving this to above the `ogp_site_url`, then using it to set that URL, which means it will provide the correct base URL for the ogp_site_url on all pages and versions:
```python
ogp_site_url = html_baseurl
```
This is tested and working in LXD's documentation. I intend to update the starter pack to resolve this issue, but want to wait until some branching changes are settled. This is here as a reminder to myself to resolve this after.
Contributor guide
Assessment
This issue has not been assessed yet.