# What this PR does
- Restructure the OnCall documentation to align with Grafana Labs
[documentation structure
guidance](https://grafana.com/docs/writers-toolkit/structure/).
- Updates documentation front matter to include all required fields.
## Which issue(s) this PR fixes
Related to issue #3700
## Checklist
- [ ] Unit, integration, and e2e (if applicable) tests updated
- [ ] Documentation added (or `pr:no public docs` PR label added if not
required)
- [ ] `CHANGELOG.md` updated (or `pr:no changelog` PR label added if not
required)
---------
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
# What this PR does
The `docs/reference` shortcode supports contextual destinations and
version inference.
`<ONCALL VERSION>` is inferred to match the version of the documentation
set. For example, the inferred version for the page
/docs/grafana/oncall/latest/get-started/ is "latest". It can also be
overriden using front matter.
Given the same page, but with the additional front matter
`oncall_version: next`, the variable is substituted with "next" rather
than "latest".
Contextual destinations are achieved using repeated labels in the
shortcode inner text. The format is [<LABEL>]: "<PAGE PATH PREFIX> ->
<HUGO REFERENCE>".
- _`<LABEL>`_ matches the reference style link label used in the rest of
the text.
- _`<PAGE PATH PREFIX>`_ is matched against the page during the
production build. If the match is successful, the destination that is
used is _`<HUGO REFERENCE>`_. The first matching prefix is used, not the
longest matching prefix.
## Which issue(s) this PR fixes
- Broken links due to ambiguous relref resolution. Any relref parameter
that does not start with either `/`, `./`, or `../` can resolve
ambiguously and is resulting in broken link behavior on the current
site.
- Broken links in Grafana Cloud. We mount OnCall documentation in
Grafana Cloud. In https://github.com/grafana/website/pull/13872 the
location will become /docs/grafana-cloud/alerting-and-irm/oncall. This
PR is intended to be merged alongside that PR.
---------
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Joey Orlando <joey.orlando@grafana.com>
If a page is removed in a future version, the presence of a "latest"
absolute alias in a previous version can redirect that removed page.
**Notes for reviewer:**
I would like to make similar changes for older, previously published
versions.
I believe you are only publishing documentation on specific tag events
and are not maintaining long lived release branches for backporting
fixes into.
If my understanding is correct, I will make the changes in the website
repository
(https://github.com/grafana/website/tree/master/content/docs/oncall).
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
