canonical / canonical/sphinx-stack

ogp_site_url example structure breaks if applied to versioned docs

Open
#513 0 comments 0 reactions 1 assignee Claimed by @minaelee View on GitHub
bug
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.