Update all links to use docs/reference style (#2456)

# 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>

.github/CODEOWNERS

@@ -4,4 +4,14 @@
 CHANGELOG.md
 
 /grafana-plugin @grafana/grafana-oncall-frontend
+
 /docs @grafana/docs-gops
+
+# `make docs` procedure is owned by @jdbaldry of @grafana/docs-squad.
+/.github/workflows/update-make-docs.yml @jdbaldry
+/.github/workflows/publish-technical-documentation-next.yml @jdbaldry
+/.github/workflows/publish-technical-documentation-release.yml @jdbaldry
+/docs/Makefile @jdbaldry
+/docs/docs.mk @jdbaldry
+/docs/make-docs @jdbaldry
+/docs/variables.mk @jdbaldry

.github/workflows/linting-and-tests.yml

@@ -83,8 +83,9 @@ jobs:
         # -e HUGO_REFLINKSERRORLEVEL=ERROR prevents merging broken refs with the downside
         # that no refs to external content can be used as these refs will not resolve in the
         # docs-base image.
+        # Use alternative image (dbd975af06) until make-docs 3.0.0 is rolled out everywhere.
         run: |
-          docker run -v ${PWD}/docs/sources:/hugo/content/docs/oncall/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'make hugo'
+          docker run -v ${PWD}/docs/sources:/hugo/content/docs/oncall/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:dbd975af06 /bin/bash -c 'echo -e "---\\nredirectURL: /hugo/content/docs/oncall/latest/\\ntype: redirect\\nversioned: true\\n---\\n" > /hugo/content/docs/oncall/_index.md; make hugo'
 
   lint-migrations-backend-mysql-rabbitmq:
     name: "Lint database migrations"

.github/workflows/update-make-docs.yml

@@ -0,0 +1,27 @@
+name: Update `make docs` procedure
+on:
+  schedule:
+    - cron: '0 7 * * 1-5'
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Update procedure
+        if: github.repository != 'grafana/writers-toolkit'
+        run: |
+          curl -s -Lo docs/docs.mk https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+          curl -s -Lo docs/make-docs https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+          if git diff --exit-code; then exit 0; fi
+          BRANCH="$(date +%Y-%m-%d)/update-make-docs"
+          git checkout -b "${BRANCH}"
+          git add .
+          git config --local user.email "bot@grafana.com"
+          git config --local user.name "grafanabot"
+          git commit -m "Update \`make docs\` procedure"
+          git push -v origin "refs/heads/${BRANCH}"
+          gh pr create --fill
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -107,5 +107,5 @@ repos:
         name: markdownlint
         entry: markdownlint --fix --ignore grafana-plugin/node_modules --ignore grafana-plugin/dist --ignore docs **/*.md
       - id: markdownlint
-        name: markdownlint - docs
-        entry: markdownlint --fix -c ./docs/.markdownlint.json ./docs/**/*.md
+        name: markdownlint - docs/sources
+        entry: markdownlint --fix --ignore README.md -c ./docs/.markdownlint.json ./docs/sources/**/*.md

docs/.markdownlint.json

@@ -4,5 +4,8 @@
     "line_length": "160"
   },
   "MD025": false,
-  "MD036": false
+  "MD033": false,
+  "MD036": false,
+  "MD052": false,
+  "MD053": false
 }

docs/docs.mk

@@ -1,3 +1,5 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# 4.0.0 (2023-06-06)
 include variables.mk
 -include variables.mk.local
 
@@ -52,6 +54,11 @@ ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
 export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
 endif
 
+# Container image used for vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
 # PATH-like list of directories within which to find projects.
 # If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
 ifeq ($(origin REPOS_PATH), undefined)
@@ -91,17 +98,17 @@ docs-no-pull: make-docs
 .PHONY: docs-debug
 docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
 docs-debug: make-docs
-	WEBSITE_EXEC='hugo server --debug' $(PWD)/make-docs $(PROJECTS)
+	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(PWD)/make-docs $(PROJECTS)
 
 .PHONY: doc-validator
-doc-validator: ## Run docs-validator on the entire docs folder.
+doc-validator: ## Run doc-validator on the entire docs folder.
 doc-validator: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(PWD)/make-docs $(PROJECTS)
 
-.PHONY: doc-validator/%
-doc-validator/%: ## Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
-doc-validator/%: make-docs
-	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) DOC_VALIDATOR_INCLUDE=$(subst doc-validator/,,$@) $(PWD)/make-docs $(PROJECTS)
+.PHONY: vale
+vale: ## Run vale on the entire docs folder.
+vale: make-docs
+	DOCS_IMAGE=$(VALE_IMAGE) $(PWD)/make-docs $(PROJECTS)
 
 .PHONY: update
 update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.

docs/make-docs

@@ -1,5 +1,6 @@
 #!/bin/sh
 # The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs.
+# 4.1.0 (2023-06-16)
 
 set -ef
 
@@ -8,9 +9,11 @@ readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}"
 readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}"
 
 readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}"
+readonly DOC_VALIDATOR_SKIP_CHECKS="${DOC_VALIDATOR_SKIP_CHECKS:-^image-}"
 
 readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}"
-readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server}"
+readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}"
+readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}"
 # If set, the docs-base image will run a prebuild script that sets up Hugo mounts.
 readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}"
 
@@ -59,23 +62,33 @@ fi
 SOURCES_as_code='as-code-docs'
 SOURCES_enterprise_metrics='backend-enterprise'
 SOURCES_enterprise_metrics_='backend-enterprise'
-SOURCES_grafana_cloud='cloud-docs'
+SOURCES_grafana_cloud='website'
 SOURCES_grafana_cloud_k6='k6-docs'
+SOURCES_grafana_cloud_data_configuration_integrations='cloud-onboarding'
+SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk'
+SOURCES_grafana_cloud_machine_learning='machine-learning'
 SOURCES_helm_charts_mimir_distributed='mimir'
 SOURCES_helm_charts_tempo_distributed='tempo'
 SOURCES_opentelemetry='opentelemetry-docs'
+SOURCES_plugins_grafana_splunk_datasource='splunk-datasource'
 
 VERSIONS_as_code='UNVERSIONED'
 VERSIONS_grafana_cloud='UNVERSIONED'
 VERSIONS_grafana_cloud_k6='UNVERSIONED'
+VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED'
+VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED'
+VERSIONS_grafana_cloud_machine_learning='UNVERSIONED'
 VERSIONS_opentelemetry='UNVERSIONED'
 VERSIONS_technical_documentation='UNVERSIONED'
+VERSIONS_website='UNVERSIONED'
 VERSIONS_writers_toolkit='UNVERSIONED'
 
+PATHS_grafana_cloud='content/docs/grafana-cloud'
 PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed'
 PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed'
 PATHS_mimir='docs/sources/mimir'
 PATHS_tempo='docs/sources/tempo'
+PATHS_website='content/docs'
 
 # identifier STR
 # Replace characters that are not valid in an identifier with underscores.
@@ -138,6 +151,13 @@ proj_url() {
 $1
 POSIX_HERESTRING
 
+  if [ "${_project}" = 'website' ]; then
+    echo "http://localhost:${DOCS_HOST_PORT}/docs/"
+
+    unset _project _version
+    return
+  fi
+
   if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
     echo "http://localhost:${DOCS_HOST_PORT}/docs/${_project}/"
   else
@@ -165,14 +185,43 @@ proj_dst() {
 $1
 POSIX_HERESTRING
 
+  if [ "${_project}" = 'website' ]; then
+    echo '/hugo/content/docs'
+
+    unset _project _version
+    return
+  fi
+
   if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
     echo "/hugo/content/docs/${_project}"
   else
     echo "/hugo/content/docs/${_project}/${_version}"
   fi
+
   unset _project _version
 }
 
+# repo_path returns the host path to the project repository.
+# It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
+repo_path() {
+  _repo="$1"
+  IFS=:
+  for lookup in ${REPOS_PATH}; do
+    if [ -d "${lookup}/${_repo}" ]; then
+      echo "${lookup}/${_repo}"
+      unset _path _repo
+      return
+    fi
+  done
+  unset IFS
+
+  echo "ERRR: could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'." >&2
+  echo "NOTE: you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'." >&2
+  echo "NOTE: if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}." >&2
+  unset _repo
+  exit 1
+}
+
 # proj_src returns the host path to content source for a project.
 # It expects a complete project structure as input.
 # It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
@@ -181,21 +230,10 @@ proj_src() {
 $1
 POSIX_HERESTRING
 
-  IFS=:
-  for lookup in ${REPOS_PATH}; do
-    if [ -d "${lookup}/${_repo}" ]; then
-      echo "${lookup}/${_repo}/${_path}"
-      unset _path _repo
-      return
-    fi
-  done
-  unset IFS
+  _repo="$(repo_path "${_repo}")"
+  echo "${_repo}/${_path}"
 
-  echo "ERRR: could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'." >&2
-  echo "NOTE: you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'." >&2
-  echo "NOTE: if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}." >&2
   unset _path _repo
-  exit 1
 }
 
 # proj_canonical returns the canonical absolute path partial URI for a project.
@@ -205,11 +243,19 @@ proj_canonical() {
 $1
 POSIX_HERESTRING
 
+  if [ "${_project}" = 'website' ]; then
+    echo '/docs'
+
+    unset _project _version
+    return
+  fi
+
   if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
     echo "/docs/${_project}"
   else
     echo "/docs/${_project}/${_version}"
   fi
+
   unset _project _version
 }
 
@@ -262,6 +308,19 @@ url_src_dst_vers="$(url_src_dst_vers "$@")"
 volumes=""
 redirects=""
 
+for arg in "$@"; do
+  IFS=: read -r _project _ _repo _ <<POSIX_HERESTRING
+${arg}
+POSIX_HERESTRING
+  if [ "${_project}" = website ]; then
+    _repo="$(repo_path website)"
+    volumes="--volume=${_repo}/config:/hugo/config"
+    volumes="${volumes} --volume=${_repo}/layouts/partials:/hugo/layouts/partials"
+    volumes="${volumes} --volume=${_repo}/layouts/shortcodes:/hugo/layouts/shortcodes"
+  fi
+  unset _project _repo
+done
+
 for x in ${url_src_dst_vers}; do
   IFS='^' read -r _url _src _dst _ver <<POSIX_HERESTRING
 $x
@@ -296,64 +355,96 @@ IFS=':' read -r image _ <<POSIX_HERESTRING
 ${DOCS_IMAGE}
 POSIX_HERESTRING
 
-if [ "${image}" = "grafana/doc-validator" ]; then
-  echo
-  "${PODMAN}" run \
-    --init \
-    --interactive \
-    --name "${DOCS_CONTAINER}" \
-    --platform linux/amd64 \
-    --rm \
-    --tty \
-    ${volumes} \
-    "${DOCS_IMAGE}" \
-    --skip-image-validation \
-    --include="${DOC_VALIDATOR_INCLUDE}" \
-    /hugo/content/docs \
-    "$(proj_canonical "$(new_proj "$1")")"
-else
-
-  cat <<EOF >/tmp/make-docs-entrypoint
+case "${image}" in
+  'grafana/doc-validator')
+    proj="$(new_proj "$1")"
+    echo
+    "${PODMAN}" run \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      "--include=${DOC_VALIDATOR_INCLUDE}" \
+      "--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
+      /hugo/content/docs \
+      "$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
+    ;;
+  'grafana/vale')
+    proj="$(new_proj "$1")"
+    echo
+    "${PODMAN}" run \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      "--minAlertLevel=${VALE_MINALERTLEVEL}" \
+      --config=/etc/vale/.vale.ini \
+      --output=line \
+      /hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
+    ;;
+  *)
+    tempfile="$(mktemp -t make-docs.XXX)"
+    cat <<EOF >"${tempfile}"
 #!/usr/bin/env bash
 for redirect in ${redirects}; do
   IFS='^' read -r path ver <<<"\${redirect}"
-  echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\n---\\n" > "\${path/\${ver}/_index.md}"
-
-  if [[ -n "${WEBSITE_MOUNTS}" ]]; then
-    unset WEBSITE_SKIP_MOUNTS
-  fi
+  echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}"
 done
 
+for x in "${url_src_dst_vers}"; do
+  IFS='^' read -r _ _ dst _ <<<"\${x}"
+
+  while [[ -n "\${dst}" ]]; do
+    touch "\${dst}/_index.md"
+    dst="\${dst%/*}"
+  done
+done
+
+if [[ -n "${WEBSITE_MOUNTS}" ]]; then
+  unset WEBSITE_SKIP_MOUNTS
+fi
+
 ${WEBSITE_EXEC}
 EOF
-  chmod +x /tmp/make-docs-entrypoint
-  volumes="${volumes} --volume=/tmp/make-docs-entrypoint:/entrypoint"
-  readonly volumes
+    chmod +x "${tempfile}"
+    volumes="${volumes} --volume=$(realpath "${tempfile}"):/entrypoint"
+    readonly volumes
 
-  echo
-  echo "Documentation will be served at the following URLs:"
-  for x in ${url_src_dst_vers}; do
-    IFS='^' read -r url _ _ <<POSIX_HERESTRING
+    echo
+    echo "Documentation will be served at the following URLs:"
+    for x in ${url_src_dst_vers}; do
+      IFS='^' read -r url _ _ <<POSIX_HERESTRING
 $x
 POSIX_HERESTRING
 
-    if [ -n "${url}" ]; then
-      echo "  ${url}"
-    fi
-  done
+      if [ -n "${url}" ]; then
+        if [ "${_url}" != "arbitrary" ]; then
+          echo "  ${url}"
+        fi
+      fi
+    done
 
-  echo
-  "${PODMAN}" run \
-    --env "HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL}" \
-    --init \
-    --interactive \
-    --name "${DOCS_CONTAINER}" \
-    --platform linux/amd64 \
-    --publish "${DOCS_HOST_PORT}:3002" \
-    --publish "3003:3003" \
-    --rm \
-    --tty \
-    ${volumes} \
-    "${DOCS_IMAGE}" \
-    /entrypoint
-fi
+    echo
+    "${PODMAN}" run \
+      --env "HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL}" \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --publish "${DOCS_HOST_PORT}:3002" \
+      --publish "3003:3003" \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      /entrypoint
+    ;;
+esac

docs/sources/escalation-chains-and-routes/_index.md

@@ -11,7 +11,7 @@ Often alerts from monitoring systems need to be sent to different escalation cha
 ## Routes
 
 Routes are used to determine which escalation chain should be used for a specific alert
-group. A route's ["Routing Templates"]({{< relref "jinja2-templating#routing-template" >}})
+group. A route's ["Routing Templates"][routing-template]
 are evaluated for each alert and **the first matching route** is used to determine the
 escalation chain and chatops channels.
 
@@ -27,7 +27,7 @@ escalation chain and chatops channels.
 2. Click **Add route** button to create a new route
 3. Click **Edit** button to edit `Routing Template`. The routing template must evaluate to `True` for it to apply
 4. Select channels in **Publish to Chatops** section
-   > **Note:** If **Publish to Chatops** section does not exist, connect Chatops integrations first, see more in [docs]({{< relref notify >}})
+   > **Note:** If **Publish to Chatops** section does not exist, connect Chatops integrations first, see more in [docs][notify]
 5. Select **Escalation Chain** from the list
 6. If **Escalation Chain** does not exist, click **Add new escalation chain** button to create a new one, it will open in a new tab.
 7. Once created, **Reload list**, and select the new escalation chain
@@ -45,7 +45,7 @@ Users can create escalation chains to configure different type of escalation wor
 For example, you can create a chain that will notify on-call users with high priopity, and
 another chain that will only send a message into a Slack channel.
 
-Escalation chains determine Who and When to notify. [How to notify]({{< relref notify >}}) is set by the user, based on their own preferences.
+Escalation chains determine Who and When to notify. [How to notify][notify] is set by the user, based on their own preferences.
 
 ### Types of escalation steps
 
@@ -59,14 +59,9 @@ from an on-call schedule.
 * `Notify whole slack channel` - send a notification to a slack channel (not recommended
 to use as it will spam the channel).
 * `Notify Slack User Group` - send a notification to a slack user group.
-* `Trigger outgoing webhook` - trigger an [outgoing webhook]({{< relref outgoing-webhooks
-
->}}).
-<https://en.wikipedia.org/>
-
+* `Trigger outgoing webhook` - trigger an [outgoing webhook][outgoing-webhooks].
 * `Notify users one by one (round robin)` - each notification will be sent to a group of
-users one by one, in sequential order in [round robin fashion](<https://en.wikipedia.org/>
-wiki/Round-robin_item_allocation).
+users one by one, in sequential order in [round robin fashion](https://en.wikipedia.org/wiki/Round-robin_item_allocation).
 * `Continue escalation if current time is in range` - continue escalation only if current
 time is in specified range. It will wait for the specfied time to continue escalation.
 Useful when you want to get escalation only during working hours
@@ -87,7 +82,7 @@ User can configure two types of personal notification chains:
 
 In the escalation step, user can select which type of notification to use.
 
-Check more information on [Personal Notification Preferences]({{< relref notify >}}) page.
+Check more information on [Personal Notification Preferences][notify] page.
 
 ### Manage Escalation Chains
 
@@ -102,3 +97,14 @@ Check more information on [Personal Notification Preferences]({{< relref notify
 
 > **Important:** Linked Integrations and Routes are displayed in the right panel. Any change in the Escalation Chain will
 affect all linked Integrations and Routes.
+
+{{% docs/reference %}}
+[notify]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/notify"
+[notify]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/notify"
+
+[outgoing-webhooks]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/outgoing-webhooks"
+[outgoing-webhooks]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/outgoing-webhooks"
+
+[routing-template]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating#routing-template"
+[routing-template]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating#routing-template"
+{{% /docs/reference %}}

docs/sources/get-started/_index.md

@@ -30,21 +30,21 @@ Grafana OnCall is available both in Grafana Cloud and Grafana Open Source.
 
 OnCall is available in Grafana Cloud automatically:
 
-1. Create or log in into [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user)
+1. Create or log in into [Grafana Cloud account](/auth/sign-up/create-user)
 2. Sign in to your Grafana stack
 3. Choose **Alerts and IRM** from the left menu
 4. Click **OnCall** to access Grafana OnCall
 
-Otherwise you'll need to install [Open Source Grafana OnCall]({{< relref "../open-source" >}}) on your own.
+Otherwise you'll need to install [Open Source Grafana OnCall][open-source] on your own.
 
 ## How to configure Grafana OnCall
 
-* Users with [Admin role]({{< relref "user-and-team-management" >}}) can configure Alert rules (Integrations, Routes, etc)
+* Users with [Admin role][user-and-team-management] can configure Alert rules (Integrations, Routes, etc)
 to define **when and which users to notify**
-* OnCall users with [Editor role]({{< relref "user-and-team-management" >}}) can work with Alerts Groups and set up personal settings,
+* OnCall users with [Editor role][user-and-team-management] can work with Alerts Groups and set up personal settings,
 e.g. **how to notify**.
 
-> **Note:** If your role is **Editor**, you can skip to [**Learn Alert Workflow**]({{< relref "#learn-about-the-alert-workflow" >}}) section
+> **Note:** If your role is **Editor**, you can skip to [**Learn Alert Workflow**](#learn-about-the-alert-workflow) section
 of this doc
 
 ## Get alerts into Grafana OnCall and configure rules
@@ -73,19 +73,19 @@ send a demo alert.
 4. Acknowledge and resolve the test alert group
 
 For more information on Grafana OnCall integrations and further configuration guidance, refer to
-[Grafana OnCall integrations]({{< relref "../integrations" >}})
+[Grafana OnCall integrations][integrations]
 
 ### Review and modify alert templates
 
 Review and customize templates to interpret monitoring alerts and minimize noise. Group alerts, enable auto-resolution,
 customize visualizations and notifications by extracting data from alerts. See more details in the
-[Jinja2 templating]({{< relref "../jinja2-templating" >}}) section.
+[Jinja2 templating][jinja2-templating] section.
 
 ### Configure scalation Chains
 
 Escalation chains are a set of steps that define who to notify, and when.
 
-See more details in the [Escalation Chains]({{< relref "../escalation-chains-and-routes#escalation-chains" >}}) section.
+See more details in the [Escalation Chains][escalation-chains] section.
 
 Escalation Chains are customizable automated alert routing steps that enable you to specify who is notified for a certain
 alert. In addition to escalation chains, you can configure Routes to send alerts to different escalation chains depending
@@ -106,14 +106,14 @@ Alerts from this integration will now follow the escalation steps configured in
 
 For more information on Escalation Chains and more ways to customize them, refer to
 
-[Configure and manage Escalation Chains]({{< relref "escalation-chains-and-routes" >}})
+[Configure and manage Escalation Chains][escalation-chains-and-routes]
 
 Routes define which messenger channels and escalation chains to use for notifications. See more details in
-the [Routes]({{< relref "../escalation-chains-and-routes#routes" >}}) section.
+the [Routes][routes] section.
 
 ### Learn about the Alert Workflow
 
-* All Alerts in OnCall are grouped into Alert Groups ([read more about Grouping ID]({{< relref "../jinja2-templating" >}})).
+* All Alerts in OnCall are grouped into Alert Groups ([read more about Grouping ID][jinja2-templating]).
 An Alert Group can have the following, mutually exclusive states:
 * **Firing:** Once Alert Group is registered, Escalation Policy associated with it is getting started.
 Escalation policy will work while Alert Group is in this status.
@@ -150,7 +150,7 @@ Personal notification policies determine how a user is notified for a certain ty
 phone call, Slack mentions, or mobile push notification. Administrators can configure how users receive notifications
 for certain types of alerts.
 For more information on personal notification policies, refer to
-[Manage users and teams for Grafana OnCall]({{< relref "user-and-team-management" >}})
+[Manage users and teams for Grafana OnCall][user-and-team-management]
 
 To configure users personal notification policies:
 
@@ -174,9 +174,9 @@ To configure Slack for Grafana OnCall:
 6. Ensure users verify their Slack accounts in their user profile in Grafana OnCall.
 
 For further instruction on connecting to your Slack workspace, refer to
-[Slack integration for Grafana OnCall]({{< relref "../notify/slack/" >}})
+[Slack integration for Grafana OnCall][slack]
 
-Grafana OnCall also supports other ChatOps integration like [Microsoft Teams and Telegram]({{< relref "../notify" >}}).
+Grafana OnCall also supports other ChatOps integration like [Microsoft Teams and Telegram][notify].
 
 ### Add your on-call schedule
 
@@ -189,4 +189,36 @@ To integrate your on-call calendar with Grafana OnCall:
 2. Provide a schedule name.
 3. Configure the rest of the schedule settings and click Create Schedule
 
-[More information on on-call schedules.]({{< relref "on-call-schedules" >}})
+[More information on on-call schedules.][on-call-schedules]
+
+{{% docs/reference %}}
+[escalation-chains-and-routes]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/escalation-chains-and-routes"
+[escalation-chains-and-routes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/escalation-chains-and-routes"
+
+[escalation-chains]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/escalation-chains-and-routes#escalation-chains"
+[escalation-chains]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/escalation-chains-and-routes#escalation-chains"
+
+[integrations]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/integrations"
+[integrations]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations"
+
+[jinja2-templating]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating"
+[jinja2-templating]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating"
+
+[notify]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/notify"
+[notify]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/notify"
+
+[on-call-schedules]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules"
+[on-call-schedules]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules"
+
+[open-source]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/open-source"
+[open-source]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/open-source"
+
+[routes]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/escalation-chains-and-routes#routes"
+[routes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/escalation-chains-and-routes#routes"
+
+[slack]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/notify/slack"
+[slack]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/notify/slack"
+
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/insights-and-metrics/_index.md

@@ -246,7 +246,7 @@ Resource IDs are used a lot in insight logs. You can find them in web ui (exampl
 3. The URL looks like `https://<YOUR_STACK_SLUG>/a/grafana-oncall-app/integrations/C5VXMIFKKP67K`.
 4. Integration ID is `C5VXMIFKKP67K`.
 
-Alternatively you can find resource ID using public [API](https://grafana.com/docs/oncall/latest/oncall-api-reference/) or browser dev tools.
+Alternatively you can find resource ID using public [API][oncall-api-reference] or browser dev tools.
 
 Actions performed by user:
 
@@ -277,3 +277,8 @@ Actions performed with slack chatops integration:
 ```logql
 {instance_type="oncall"} | logfmt | __error__=`` | action_type = `chat_ops` and chat_ops_type=`slack`
 ```
+
+{{% docs/reference %}}
+[oncall-api-reference]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/oncall-api-reference"
+[oncall-api-reference]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference"
+{{% /docs/reference %}}

docs/sources/integrations/_index.md

@@ -18,20 +18,20 @@ An "Integration" is a main entry point for alerts being consumed by Grafana OnCa
 Integrations receive alerts on a unique API URL, interprets them using a set of templates tailored for the monitoring system, and starts
 escalations.
 
-Read more about Jinja2 templating used in OnCall [here]({{< relref "../jinja2-templating" >}}).
+Read more about Jinja2 templating used in OnCall [here][jinja2-templating].
 
 ## Learn Alert Flow Within Integration
 
 1. An Alert is received on an integration's **Unique URL** as an HTTP POST request with a JSON payload (or via
 [e-mail]({{< relref "inbound-email" >}}), for inbound e-mail integrations)
-1. Routing is determined for the incoming alert, by applying the [Routing Template]({{< relref "jinja2-templating#routing-template" >}})
-1. Alert Grouping is determined based on [Grouping Id Template]({{< relref "jinja2-templating#behavioral-template" >}})
+1. Routing is determined for the incoming alert, by applying the [Routing Template][routing-template]
+1. Alert Grouping is determined based on [Grouping Id Template][behavioral-template]
 1. An Alert Group may be acknowledged or resolved with status `_ by source` based on
-[Behaviour Templates]({{< relref "jinja2-templating#behavioral-template" >}})
+[Behaviour Templates][behavioral-template]
 1. The Alert Group is available in Web, and can be published to messengers, based on the Route's **Publish to Chatops** configuration.
-It is rendered using [Appearance Templates]({{< relref "jinja2-templating#appearance-template" >}})
+It is rendered using [Appearance Templates][appearance-template]
 1. The Alert Group is escalated to uers based on the Escalation Chains selected for the Route
-1. Users can perform actions listed in [Learn Alert Workflow]({{< relref "get-started#learn-alert-workflow" >}}) section
+1. Users can perform actions listed in [Learn Alert Workflow][learn-alert-workflow] section
 
 ## Configure and manage integrations
 
@@ -43,7 +43,7 @@ describe how to configure and customize your integrations to ensure alerts are t
 To configure an integration for Grafana OnCall:
 
 1. In Grafana OnCall, navigate to the **Integrations** tab and click **+ New integration**.
-1. Select an integration type from the [list of available integrations]({{< relref "#list-of-available-integrations" >}}).
+1. Select an integration type from the [list of available integrations](#list-of-available-integrations).
 If the integration you want isn’t listed, then select **Webhook**.
 1. Fill in a title and a description for your integration, assign it to a team, and click **Create Integration**.
 1. The Integration page will open. Here you will see details about the Integration.
@@ -54,13 +54,13 @@ Click the **How to connect** link for more information.
 
 ### Complete the integration configuration
 
-- Review and customise grouping, autoresolution, autoacknowledge, etc [templates]({{< relref "../jinja2-templating" >}})
+- Review and customise grouping, autoresolution, autoacknowledge, etc [templates][jinja2-templating]
 if you want to customise alert behaviour for your team
-- Review and customise [other templates]({{< relref "../jinja2-templating" >}}) to change how alert groups are displayed
+- Review and customise [other templates][jinja2-templating] to change how alert groups are displayed
 in different parts of Grafana OnCall: UI, messengers, emails, notifications, etc.
 - Add routes to your integration to route alerts to different users and teams based on labels or other data
 - Connect your escalation chains to routes to notify the right people, at the right time
-- Learn [how to start Maintenance Mode]({{< relref "#maintenance-mode" >}}) for an integration
+- Learn [how to start Maintenance Mode](#maintenance-mode) for an integration
 - Send demo alerts to an integration to make sure routes, templates, and escalations, are working as expected. Consider using
 `Debug Maintenance mode` to avoid sending real notifications to your team
 
@@ -103,7 +103,7 @@ More specific instructions can be found in a specific integration's documentatio
 
 "Integration templates" are Jinja2 templates which are applied to each alert to define it's rendering and behaviour.
 
-Read more in [Templates guide]({{< relref jinja2-templating>}})
+Read more in [Templates guide][jinja2-templating]
 
 For templates editor:
 
@@ -143,3 +143,20 @@ To edit the name of an integration:
 ## List of available integrations
 
 {{< section >}}
+
+{{% docs/reference %}}
+[appearance-template]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating#appearance-template"
+[appearance-template]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating#appearance-template"
+
+[behavioral-template]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating#behavioral-template"
+[behavioral-template]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating#behavioral-template"
+
+[jinja2-templating]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating"
+[jinja2-templating]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating"
+
+[learn-alert-workflow]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/get-started#learn-alert-workflow"
+[learn-alert-workflow]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/get-started#learn-alert-workflow"
+
+[routing-template]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating#routing-template"
+[routing-template]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating#routing-template"
+{{% /docs/reference %}}

docs/sources/integrations/alertmanager/index.md

@@ -15,7 +15,7 @@ weight: 300
 
 # Alertmanager integration for Grafana OnCall
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 The Alertmanager integration handles alerts from [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/).
 This integration is the recommended way to send alerts from Prometheus deployed in your infrastructure, to Grafana OnCall.
@@ -59,7 +59,7 @@ receivers:
 ## Complete the Integration Configuration
 
 Complete configuration by setting routes, templates, maintenances, etc. Read more in
-[this section]({{< relref "../../integrations/#complete-the-integration-configuration" >}})
+[this section][complete-the-integration-configuration]
 
 ## Configuring OnCall Heartbeats (optional)
 
@@ -111,5 +111,12 @@ Add receiver configuration to `prometheus.yaml` with the **OnCall Heartbeat URL*
               webhook_configs:
             - url: https://oncall-dev-us-central-0.grafana.net/oncall/integrations/v1/alertmanager/1234567890/heartbeat/
               send_resolved: false
-        
-        ```
+```
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+
+[complete-the-integration-configuration]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/integrations#complete-the-integration-configuration"
+[complete-the-integration-configuration]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations#complete-the-integration-configuration"
+{{% /docs/reference %}}

docs/sources/integrations/amazon-sns/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Amazon SNS integration for Grafana OnCall handles ticket events sent from Amazon SNS webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations
 in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Amazon SNS
@@ -35,3 +35,8 @@ in Grafana OnCall.
 2. Open this topic, then create a new subscription
 3. Choose the protocol HTTPS
 4. Add the **OnCall Integration URL** to the Amazon SNS Endpoint
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/appdynamics/index.md

@@ -18,7 +18,7 @@ weight: 500
 The AppDynamics integration for Grafana OnCall handles health rule violation events sent from AppDynamics actions.
 The integration provides grouping and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from AppDynamics
 
@@ -105,4 +105,12 @@ Grafana OnCall provides grouping and auto-resolve logic for the AppDynamics inte
 ## Complete the Integration Configuration
 
 Complete configuration by setting routes, templates, maintenances, etc. Read more in
-[this section]({{< relref "../../integrations/#complete-the-integration-configuration" >}})
+[this section][complete-the-integration-configuration]
+
+{{% docs/reference %}}
+[complete-the-integration-configuration]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/integrations#complete-the-integration-configuration"
+[complete-the-integration-configuration]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations#complete-the-integration-configuration"
+
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/datadog/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Datadog integration for Grafana OnCall handles ticket events sent from Datadog webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Datadog
 
@@ -36,3 +36,8 @@ The integration provides grouping, auto-acknowledge and auto-resolve logic via c
 5. Navigate to the Events page from the sidebar to send the test alert
 6. Type @webhook-grafana-oncall-alerts test alert
 7. Click the post button
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/elastalert/index.md

@@ -18,7 +18,7 @@ weight: 500
 The ElastAlert integration for Grafana OnCall handles ticket events sent from ElastAlert webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from ElastAlert
 
@@ -74,3 +74,8 @@ Add the following rule to ElastAlert
     alert_text: elastalert is still running
     alert_text_type: alert_text_only
 ```
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/fabric/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Fabric integration for Grafana OnCall handles ticket events sent from Fabric webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Fabric
 
@@ -35,3 +35,8 @@ The integration provides grouping, auto-acknowledge and auto-resolve logic via c
 4. Enter URL: **OnCall Integration URL**
 5. Click Verify
 6. Choose "SEND IMPACT CHANGE ALERTS" and "ALSO SEND NON-FATAL ALERTS"
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/inbound-email/index.md

@@ -27,7 +27,7 @@ You must have an Admin role to create integrations in Grafana OnCall.
 ## Grouping and auto-resolve
 
 Alert groups will be grouped by email subject and auto-resolved if the email message text equals "OK".
- This behaviour can be modified via [custom templates]({{< relref "jinja2-templating" >}}).
+ This behaviour can be modified via [custom templates][jinja2-templating].
 
 Alerts from Inbound Email integration have the following payload:
 
@@ -38,3 +38,8 @@ Alerts from Inbound Email integration have the following payload:
    "sender": "<your_email_sender_address>"
 }
 ```
+
+{{% docs/reference %}}
+[jinja2-templating]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating"
+[jinja2-templating]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating"
+{{% /docs/reference %}}

docs/sources/integrations/jira/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Jira integration for Grafana OnCall handles issue events sent from Jira webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Jira
 
@@ -49,3 +49,8 @@ Grafana OnCall provides grouping, auto-acknowledge and auto-resolve logic for th
 - Alert groups are auto-resolved when the issue is closed or deleted
 
 To customize this behaviour, consider modifying alert templates in integration settings.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/kapacitor/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Kapacitor integration for Grafana OnCall handles ticket events sent from Kapacitor webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Kapacitor
 
@@ -59,3 +59,8 @@ To send an alert from Kapacitor, you can follow these steps:
 When the condition defined in the TICKscript is met, Kapacitor will trigger the alert and send
 a POST request to the specified webhook URL with the necessary information. Make sure your webhook
 endpoint is configured to receive and process the incoming alerts from Kapacitor.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/newrelic/index.md

@@ -18,7 +18,7 @@ weight: 500
 The New Relic integration for Grafana OnCall handles ticket events sent from New Relic webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from New Relic
 
@@ -34,3 +34,8 @@ The integration provides grouping, auto-acknowledge and auto-resolve logic via c
 3. Create "Webhook" notification channel.
 4. Set the following URL: **OnCall Integration URL**
 5. Check "Payload type" is JSON.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/pingdom/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Pingdom integration for Grafana OnCall handles ticket events sent from Pingdom webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Pingdom
 
@@ -35,3 +35,8 @@ The integration provides grouping, auto-acknowledge and auto-resolve logic via c
 4. Go to "Reports" -> "Uptime" -> "Edit Check".
 5. Select `Grafana OnCall` integration in the bottom.
 6. Click "Modify Check" to save.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/prtg/index.md

@@ -18,7 +18,7 @@ weight: 500
 The PRTG integration for Grafana OnCall handles ticket events sent from PRTG webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from PRTG
 
@@ -111,3 +111,8 @@ Catch
 }
 
 ```
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/sentry/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Sentry integration for Grafana OnCall handles ticket events sent from Sentry webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Sentry
 
@@ -54,3 +54,8 @@ level, event frequency, or specific tags.
 8. Save the alert rule.
 
 Once the alert conditions are met, Sentry will trigger the webhook action and send a request to the Grafana OnCall.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/stackdriver/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Stackdriver integration for Grafana OnCall handles ticket events sent from Stackdriver webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Stackdriver
 
@@ -32,3 +32,8 @@ The integration provides grouping, auto-acknowledge and auto-resolve logic via c
 1. Create a notification channel in Stackdriver by navigating to Workspace Settings -> WEBHOOKS -> Add Webhook **OnCall Integration URL**
 
 2. Create and alert in Stackdriver by navigating to Alerting -> Policies -> Add Policy -> Choose Notification Channel using the channel set up in step 1
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/uptimerobot/index.md

@@ -18,7 +18,7 @@ weight: 500
 The UptimeRobot integration for Grafana OnCall handles ticket events sent from UptimeRobot webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from UptimeRobot
 
@@ -59,3 +59,8 @@ POST Value (JSON Format):
 1. Set URL to <http://devnull.amixr.io> or any other non-existent domain
 1. Click Checkbox next to Amixr Alert Contact (created in the previous step)
 1. Click Create Monitor
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/integrations/webhook/index.md

@@ -60,4 +60,9 @@ https://a-prod-us-central-0.grafana.net/integrations/v1/formatted_webhook/m12xmI
 ```
 
 To learn how to use custom alert templates for formatted webhooks, see
-[Configure alerts templates]({{< relref "jinja2-templating" >}}).
+[Configure alerts templates][jinja2-templating].
+
+{{% docs/reference %}}
+[jinja2-templating]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/jinja2-templating"
+[jinja2-templating]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/jinja2-templating"
+{{% /docs/reference %}}

docs/sources/integrations/zendesk/index.md

@@ -18,7 +18,7 @@ weight: 500
 The Zendesk integration for Grafana OnCall handles ticket events sent from Zendesk webhooks.
 The integration provides grouping, auto-acknowledge and auto-resolve logic via customizable alert templates.
 
-> You must have the [role of Admin]({{< relref "user-and-team-management" >}}) to be able to create integrations in Grafana OnCall.
+> You must have the [role of Admin][user-and-team-management] to be able to create integrations in Grafana OnCall.
 
 ## Configuring Grafana OnCall to Receive Alerts from Zendesk
 
@@ -64,3 +64,8 @@ Grafana OnCall provides grouping, auto-acknowledge and auto-resolve logic for th
 - Alert groups are auto-resolved when the ticket status is set to "Solved"
 
 To customize this behaviour, consider modifying alert templates in integration settings.
+
+{{% docs/reference %}}
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+{{% /docs/reference %}}

docs/sources/notify/_index.md

@@ -18,7 +18,7 @@ weight: 800
 # Notify people
 
 Grafana OnCall directly supports the export of alert notifications to some popular messaging applications like Slack and
-Telegram. You can use [outgoing webhooks]({{< relref "outgoing-webhooks" >}}) for applications that aren't directly
+Telegram. You can use [outgoing webhooks][outgoing-webhooks] for applications that aren't directly
 supported.
 
 To configure supported messaging apps, see the following topics:
@@ -49,3 +49,8 @@ To configure a users notification policy:
 
 1. Click **Add notification step** and use the dropdowns to specify the notification method and frequency. Notification steps will be followed in the order they
 are listed.
+
+{{% docs/reference %}}
+[outgoing-webhooks]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/outgoing-webhooks"
+[outgoing-webhooks]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/outgoing-webhooks"
+{{% /docs/reference %}}

docs/sources/notify/phone-calls-sms/index.md

@@ -17,7 +17,7 @@ weight: 100
 
 # Phone Calls and SMS notifications
 
-Grafana OnCall Cloud includes SMS and Phone notifications, OSS users [could leverage]({{< relref "open-source" >}}) Grafana Cloud as a relay or
+Grafana OnCall Cloud includes SMS and Phone notifications, OSS users [could leverage][open-source] Grafana Cloud as a relay or
 configure other providers like Twilio.
 
 ## Are there additional costs for outgoing calls/sms?
@@ -41,4 +41,12 @@ In order to learn the phone number used by OnCall, make a test call at the "Phon
 There are cases when OnCall is not able to make phone calls or send SMS to certain regions or specific phone numbers.
 We're working hard to fix such cases, but kindly asking to test your personal notification chain to make sure OnCall
 is able to notify you. Also we suggest to back up Phone Calls and SMS with other notification methods such as
-[Mobile App]({{< relref "mobile-app" >}}).
+[Mobile App][mobile-app].
+
+{{% docs/reference %}}
+[mobile-app]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/mobile-app"
+[mobile-app]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/mobile-app"
+
+[open-source]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/open-source"
+[open-source]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/open-source/"
+{{% /docs/reference %}}

docs/sources/notify/slack/index.md

@@ -29,7 +29,7 @@ To install the Slack integration, you must have Admin permissions in your Grafan
 that you’d like to integrate with.
 
 For Open Source Grafana OnCall Slack installation guidance, refer to
-[Open Source Grafana OnCall]({{< relref "open-source" >}}).
+[Open Source Grafana OnCall][open-source].
 
 ## Install Slack integration for Grafana OnCall
 
@@ -117,3 +117,8 @@ Use message shortcuts to add resolution notes directly from Slack. Message short
 1. Hover over the message and select **More actions** from the menu options.
 1. Select **Add as resolution note**.
 1. The Grafana OnCall app will react to the message in Slack with the memo emoji and add the message to the alert group timeline.
+
+{{% docs/reference %}}
+[open-source]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/open-source"
+[open-source]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/open-source"
+{{% /docs/reference %}}

docs/sources/on-call-schedules/_index.md

@@ -19,14 +19,14 @@ weight: 700
 - Users with Viewer role cannot receive alert notifications, therefore, cannot be on-call.
 
 For more information about permissions, refer to
-[Manage users and teams for Grafana OnCall]({{< relref "user-and-team-management" >}})
+[Manage users and teams for Grafana OnCall][user-and-team-management]
 
 ### Web-based schedule
 
 Configure and manage on-call schedules directly in the Grafana OnCall plugin. Easily configure and preview rotations,
 see teammates' time zones, and add overrides.
 
-Learn more about [Web-based schedules]({{< relref "web-schedule" >}})
+Learn more about [Web-based schedules][web-schedule]
 
 ### iCal import
 
@@ -34,7 +34,7 @@ Use any calendar service that uses the iCal format to manage and customize on-ca
 shifts from your calendar app to Grafana OnCall for widely accessible scheduling. iCal imports appear in Grafana
 OnCall as read-only schedules but can be leveraged similarly to a web-based schedule.
 
-Learn more about [iCal import schedules]({{< relref "ical-schedules" >}})
+Learn more about [iCal import schedules][ical-schedules]
 
 ### Terraform
 
@@ -44,3 +44,14 @@ read-only and cannot be edited from the UI.
 
 To learn more, read our [Get started with Grafana OnCall and Terraform](
 <https://grafana.com/blog/2022/08/29/get-started-with-grafana-oncall-and-terraform/>) blog post.
+
+{{% docs/reference %}}
+[ical-schedules]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/ical-schedules"
+[ical-schedules]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/ical-schedules"
+
+[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
+[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
+
+[web-schedule]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/web-schedule"
+[web-schedule]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/web-schedule"
+{{% /docs/reference %}}

docs/sources/on-call-schedules/api-terraform-schedule/_index.md

@@ -18,4 +18,9 @@ teams in the org, we suggest considering storing schedules as code.
 
 - [Get started with Grafana OnCall and Terraform (blogpost)](https://grafana.com/blog/2022/08/29/get-started-with-grafana-oncall-and-terraform/)
 - [Grafana Terraform provider reference (OnCall resources are managed using this provider)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_schedule)
-- [OnCall API]({{< relref "oncall-api-reference" >}})
+- [OnCall API][oncall-api-reference]
+
+{{% docs/reference %}}
+[oncall-api-reference]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/oncall-api-reference"
+[oncall-api-reference]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference"
+{{% /docs/reference %}}

docs/sources/on-call-schedules/ical-schedules/index.md

@@ -20,7 +20,7 @@ OnCall as read-only schedules but can be leveraged similarly to a web-based sche
 > Unfortunately there is a known limitation with Google Calendar import and export.
 > Google may take up to 24h to import OnCall's calendar (OnCall -> Google) and sometimes our customers report delay in
 > exporting (Google Calendar -> OnCall). If actual calendar is critical for you, we suggest checking
-> [web-based scheduling]({{< relref "web-schedule" >}}).
+> [web-based scheduling]
 
 ## Before you begin
 
@@ -99,3 +99,8 @@ contain a level marker result in all overlapping users receiving notifications.
 For example, users AliceGrafana and BobGrafana have overlapping schedules but BobGrafana is the intended primary
 contact. The calendar events titles would be `[L1] BobGrafana` and `[L0] AliceGrafana` - In this case AliceGrafana
 maintains the default [L0] status, and would not receive notifications during the overlapping time with BobGrafana.
+
+{{% docs/reference %}}
+[web-schedule]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/web-schedule"
+[web-schedule]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/web-schedule"
+{{% /docs/reference %}}

docs/sources/oncall-api-reference/integrations.md

@@ -74,7 +74,7 @@ The above command returns JSON structured in the following way:
 
 Integrations are sources of alerts and alert groups for Grafana OnCall.
 For example, to learn how to integrate Grafana OnCall with Alertmanager see
-[Alertmanager]({{< relref "../integrations/alertmanager" >}}).
+[Alertmanager][alertmanager].
 
 **HTTP request**
 
@@ -314,3 +314,8 @@ curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
 **HTTP request**
 
 `DELETE {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/`
+
+{{% docs/reference %}}
+[alertmanager]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/integrations/alertmanager"
+[alertmanager]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations/alertmanager"
+{{% /docs/reference %}}

docs/variables.mk

@@ -1,2 +1,5 @@
 # List of projects to provide to the make-docs script.
-PROJECTS = oncall
+PROJECTS := oncall
+
+# Use alternative image until make-docs 3.0.0 is rolled out.
+export DOCS_IMAGE := grafana/docs-base:dbd975af06