Update links #11923
Update links #11923
Conversation
github-actions
bot
added
the
type/docs
There was a problem hiding this comment.
If we use <LOKI_VERSION> instead of latest, then these links will resolve correctly independent of the documentation version.
I've made suggestions on one file but we should use it in all of the hunks in this patch.
The example in Writers' Toolkit uses Grafana but the same behavior applies here: https://grafana.com/docs/writers-toolkit/write/links/#examples.
For more information about how version substitution works, refer to About version substitution.
| @@ -8,7 +8,7 @@ weight: 1 | |||
|
|
|||
| ## Stable Releases | |||
|
|
|||
| Loki releases (this includes [Promtail](/clients/promtail), [Loki Canary](/operations/loki-canary/), etc) use the following | |||
| Loki releases (this includes [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/), etc) use the following | |||
There was a problem hiding this comment.
| Loki releases (this includes [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/), etc) use the following | |
| Loki releases (this includes [Promtail](https://grafana.com/docs/loki/<LOKI_VERSION>/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/<LOKI_VERSION>/operations/loki-canary/), etc) use the following |
There was a problem hiding this comment.
I literally do not understand how there is any difference between specifying latest in the URL and specifying latest as the <LOKI_VERSION>. It's still "latest".
There was a problem hiding this comment.
Because these docs will also be in next and then they will link to latest instead of next.
And when you release the next version of Loki, the previous docs will also link to latest instead of linking within the current version.
You can choose to not use the <LOKI_VERSION> syntax but it will mean that you need to update your links as part of every release and it will negatively impact backporting.
There was a problem hiding this comment.
Trying to think this through.... Going on what is currently documented in the Writers Toolkit, if the root _index/md file has LOKI_VERSION: latest then you still have the same problem of the links in next pointing to latest.
It isn't documented, but for links to resolve correctly wouldn't you need the following?
Latest release (Loki 2.9) -> _index/md file has LOKI_VERSION: latest?
Or even better, root _index/md file has LOKI_VERSION: 2.9?
Main branch -> root _index/md file has LOKI_VERSION: next?
There was a problem hiding this comment.
https://grafana.com/docs/writers-toolkit/write/shortcodes/#about-version-substitution
The shortcode substitutes the special syntax
<SOMETHING_VERSION>with the version inferred from the page’s URL. If the page’s URL has the prefix/docs/grafana/latest/, the shortcode replaces the syntax<SOMETHING_VERSION>withlatestin the final URL.You can override version inference by including additional metadata in the front matter of the file. To override the value of
<GRAFANA_VERSION>, set theGRAFANA_VERSIONparameter in the page’s front matter. For example, to set the version to next irrespective of the source content version, add the following to the front matter:GRAFANA_VERSION: next.
If you don't set the front matter, the version is inferred from the page's URL
There was a problem hiding this comment.
The front matter override is primarily there so that other projects can specify the version of the documentation they are interested in linking to. For example, Grafana Cloud sets GRAFANA_VERSION: next so that all links to Grafana documentation go to the next version. The Mimir helm chart sets MIMIR_DOCS_VERSION to v2.10.x so that they can update a single place when the Mimir helm chart is updated to be compatible with a different version of Mimir and then all links point to the correct version of the Mimir docs.
There was a problem hiding this comment.
If you don't set the front matter, the version is inferred from the page's URL
The way that the Writers Toolkit is currently written tells you to set the value for the version in the root _index.md file. I would never have guessed that that was an optional step.
|
I have been unable to update this PR for the past two days. Closing this and opened a new PR (#11956). |
Which issue(s) this PR fixes:
Fixes broken links in https://grafana.com/docs/loki/latest/release-notes/cadence/