fix right-hand navigation in API docs (#4546)

# What this PR does The right-hand side navigation in the OnCall API public docs ([example](https://grafana.com/docs/oncall/latest/oncall-api-reference/alertgroups/)) doesn’t render as expected vs. what we see in the Grafana API public docs ([example](https://grafana.com/docs/grafana/latest/developers/http_api/folder/); 2nd screenshot). This PR fixes that ([convo on Slack](https://raintank-corp.slack.com/archives/C045CTY1QEP/p1718388424649359)). ![Screenshot 2024-06-14 at 14 05 03](https://github.com/grafana/oncall/assets/9406895/0636d9d7-2f58-4c82-91b5-5b4af0dd3524) ![Screenshot 2024-06-14 at 14 06 36 (1)](https://github.com/grafana/oncall/assets/9406895/7a5bc2c8-ccb2-4b53-b982-d7d7596f90e2)
2024-06-17 11:31:35 -04:00 · 2024-06-17 11:31:35 -04:00 · c5b76a5869
commit c5b76a5869
parent 8f3cdc3ccc
15 changed files with 98 additions and 70 deletions
--- a/docs/sources/oncall-api-reference/alertgroups.md
+++ b/docs/sources/oncall-api-reference/alertgroups.md
@ -4,7 +4,9 @@ title: Alert groups HTTP API
 weight: 400
 ---

-# List alert groups
+# Alert groups HTTP API
+
+## List alert groups

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/" \
@ -57,7 +59,7 @@ These available filter parameters should be provided as `GET` arguments:

 `GET {{API_URL}}/api/v1/alert_groups/`

-# Alert group details
+## Alert group details

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \
@ -69,7 +71,7 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \

 `GET {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>`

-# Acknowledge an alert group
+## Acknowledge an alert group

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \
@ -81,7 +83,7 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \

 `POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/acknowledge`

-# Unacknowledge an alert group
+## Unacknowledge an alert group

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \
@ -93,7 +95,7 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \

 `POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/unacknowledge`

-# Resolve an alert group
+## Resolve an alert group

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \
@ -105,7 +107,7 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \

 `POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/resolve`

-# Unresolve an alert group
+## Unresolve an alert group

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \
@ -117,7 +119,7 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \

 `POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/unresolve`

-# Delete an alert group
+## Delete an alert group

 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \
--- a/docs/sources/oncall-api-reference/alerts.md
+++ b/docs/sources/oncall-api-reference/alerts.md
@ -4,7 +4,9 @@ title: Alerts HTTP API
 weight: 100
 ---

-# List Alerts
+# Alerts HTTP API
+
+## List Alerts

 ```shell
 curl "{{API_URL}}/api/v1/alerts/" \
--- a/docs/sources/oncall-api-reference/escalation_chains.md
+++ b/docs/sources/oncall-api-reference/escalation_chains.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation_chains/
-title: Escalation Chains HTTP API
+title: Escalation chains HTTP API
 weight: 200
 ---

-# Create an escalation chain
+# Escalation chains HTTP API
+
+## Create an escalation chain

 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/" \
@ -35,7 +37,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/escalation_chains/`

-# Get an escalation chain
+## Get an escalation chain

 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
@ -58,7 +60,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/`

-# List escalation chains
+## List escalation chains

 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/" \
@ -91,7 +93,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/escalation_chains/`

-# Delete an escalation chain
+## Delete an escalation chain

 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
--- a/docs/sources/oncall-api-reference/escalation_policies.md
+++ b/docs/sources/oncall-api-reference/escalation_policies.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation_policies/
-title: Escalation Policies HTTP API
+title: Escalation policies HTTP API
 weight: 300
 ---

-# Create an escalation policy
+# Escalation policies HTTP API
+
+## Create an escalation policy

 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/" \
@ -50,7 +52,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/escalation_policies/`

-# Get an escalation policy
+## Get an escalation policy

 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
@ -71,7 +73,7 @@ The above command returns JSON structured in the following way:
 }
 ```

-# Update an escalation policy
+## Update an escalation policy

 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
@ -104,7 +106,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/`

-# List escalation policies
+## List escalation policies

 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/" \
@ -150,7 +152,7 @@ The following available filter parameter should be provided as a `GET` argument:

 `GET {{API_URL}}/api/v1/escalation_policies/`

-# Delete an escalation policy
+## Delete an escalation policy

 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
--- a/docs/sources/oncall-api-reference/integrations.md
+++ b/docs/sources/oncall-api-reference/integrations.md
@ -4,7 +4,9 @@ title: Integrations HTTP API
 weight: 500
 ---

-# Create an integration
+# Integrations HTTP API
+
+## Create an integration

 ```shell
 curl "{{API_URL}}/api/v1/integrations/" \
@ -79,7 +81,7 @@ For example, to learn how to integrate Grafana OnCall with Alertmanager refer to

 `POST {{API_URL}}/api/v1/integrations/`

-# Get integration
+## Get integration

 ```shell
 curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
@ -150,7 +152,7 @@ This endpoint retrieves an integration. Integrations are sources of alerts and a

 `GET {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/`

-# List integrations
+## List integrations

 ```shell
 curl "{{API_URL}}/api/v1/integrations/" \
@ -229,7 +231,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/integrations/`

-# Update integration
+## Update integration

 ```shell
 curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
@ -302,7 +304,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/`

-# Delete integration
+## Delete integration

 Deleted integrations will stop recording new alerts from monitoring. Integration removal won't trigger removal of
 related alert groups or alerts.
--- a/docs/sources/oncall-api-reference/on_call_shifts.md
+++ b/docs/sources/oncall-api-reference/on_call_shifts.md
@ -4,7 +4,9 @@ title: OnCall shifts HTTP API
 weight: 600
 ---

-# Create an OnCall shift
+# OnCall shifts HTTP API
+
+## Create an OnCall shift

 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/" \
@ -67,7 +69,7 @@ For more information about recurrence rules, refer to [RFC 5545](https://tools.i

 `POST {{API_URL}}/api/v1/on_call_shifts/`

-# Get OnCall shifts
+## Get OnCall shifts

 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
@ -96,7 +98,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/`

-# List OnCall shifts
+## List OnCall shifts

 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/" \
@ -157,7 +159,7 @@ The following available filter parameters should be provided as `GET` arguments:

 `GET {{API_URL}}/api/v1/on_call_shifts/`

-# Update OnCall shift
+## Update OnCall shift

 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
@ -196,7 +198,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/`

-# Delete OnCall shift
+## Delete OnCall shift

 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
--- a/docs/sources/oncall-api-reference/outgoing_webhooks.md
+++ b/docs/sources/oncall-api-reference/outgoing_webhooks.md
@ -1,10 +1,10 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/outgoing_webhooks/
-title: Outgoing Webhooks HTTP API
+title: Outgoing webhooks HTTP API
 weight: 700
 ---

-# Outgoing Webhooks
+# Outgoing webhooks

 > ⚠️ A note about actions: Before version **v1.3.11** webhooks existed as actions within the API, the /actions
 > endpoint remains available and is compatible with previous callers but under the hood it will interact with the
--- a/docs/sources/oncall-api-reference/personal_notification_rules.md
+++ b/docs/sources/oncall-api-reference/personal_notification_rules.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/personal_notification_rules/
-title: Personal Notification Rules HTTP API
+title: Personal notification rules HTTP API
 weight: 800
 ---

-# Post a personal notification rule
+# Personal notification rules HTTP API
+
+## Post a personal notification rule

 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/" \
@ -41,7 +43,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/personal_notification_rules/`

-# Get personal notification rule
+## Get personal notification rule

 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/ND9EHN5LN1DUU/" \
@ -67,7 +69,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/personal_notification_rules/<PERSONAL_NOTIFICATION_RULE_ID>/`

-# List personal notification rules
+## List personal notification rules

 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/" \
@ -129,7 +131,7 @@ The following available filter parameters should be provided as `GET` arguments:

 `GET {{API_URL}}/api/v1/personal_notification_rules/`

-# Delete a personal notification rule
+## Delete a personal notification rule

 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/NWAL6WFJNWDD8/" \
--- a/docs/sources/oncall-api-reference/resolution_notes.md
+++ b/docs/sources/oncall-api-reference/resolution_notes.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/resolution_notes/
-title: Resolution Notes HTTP API
+title: Resolution notes HTTP API
 weight: 900
 ---

-# Create a resolution note
+# Resolution notes HTTP API
+
+## Create a resolution note

 ```shell
 curl "{{API_URL}}/api/v1/resolution_notes/" \
@ -39,7 +41,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/resolution_notes/`

-# Get a resolution note
+## Get a resolution note

 ```shell
 curl "{{API_URL}}/api/v1/resolution_notes/M4BTQUS3PRHYQ/" \
@ -65,7 +67,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/resolution_notes/<RESOLUTION_NOTE_ID>/`

-# List resolution notes
+## List resolution notes

 ```shell
 curl "{{API_URL}}/api/v1/resolution_notes/" \
@ -105,7 +107,7 @@ The following available filter parameter should be provided as a `GET` argument:

 `GET {{API_URL}}/api/v1/resolution_notes/`

-# Update a resolution note
+## Update a resolution note

 ```shell
 curl "{{API_URL}}/api/v1/resolution_notes/M4BTQUS3PRHYQ/" \
@ -134,7 +136,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/resolution_notes/<RESOLUTION_NOTE_ID>/`

-# Delete a resolution note
+## Delete a resolution note

 ```shell
 curl "{{API_URL}}/api/v1/resolution_notes/M4BTQUS3PRHYQ/" \
--- a/docs/sources/oncall-api-reference/routes.md
+++ b/docs/sources/oncall-api-reference/routes.md
@ -4,7 +4,9 @@ title: Routes HTTP API
 weight: 1100
 ---

-# Create a route
+# Routes HTTP API
+
+## Create a route

 ```shell
 curl "{{API_URL}}/api/v1/routes/" \
@ -57,7 +59,7 @@ Routes allow you to direct different alerts to different messenger channels and

 `POST {{API_URL}}/api/v1/routes/`

-# Get a route
+## Get a route

 ```shell
 curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
@ -86,7 +88,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/routes/<ROUTE_ID>/`

-# List routes
+## List routes

 ```shell
 curl "{{API_URL}}/api/v1/routes/" \
@ -141,7 +143,7 @@ The following available filter parameters should be provided as `GET` arguments:

 `GET {{API_URL}}/api/v1/routes/`

-# Update route
+## Update route

 ```shell
 curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
@ -177,7 +179,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/routes/<ROUTE_ID>/`

-# Delete a route
+## Delete a route

 ```shell
 curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
--- a/docs/sources/oncall-api-reference/schedules.md
+++ b/docs/sources/oncall-api-reference/schedules.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/schedules/
-title: Schedule HTTP API
+title: Schedules HTTP API
 weight: 1200
 ---

-# Create a schedule
+# Schedules HTTP API
+
+## Create a schedule

 ```shell
 curl "{{API_URL}}/api/v1/schedules/" \
@ -55,7 +57,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/schedules/`

-# Get a schedule
+## Get a schedule

 ```shell
 curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
@ -86,7 +88,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/`

-# List schedules
+## List schedules

 ```shell
 curl "{{API_URL}}/api/v1/schedules/" \
@ -145,7 +147,7 @@ The following available filter parameter should be provided as a `GET` argument:

 `GET {{API_URL}}/api/v1/schedules/`

-# Update a schedule
+## Update a schedule

 ```shell
 curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
@ -183,7 +185,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/`

-# Delete a schedule
+## Delete a schedule

 ```shell
 curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
@ -196,7 +198,7 @@ curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \

 `DELETE {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/`

-# Export a schedule's final shifts
+## Export a schedule's final shifts

 **HTTP request**

@ -305,7 +307,7 @@ The above command returns JSON structured in the following way:
 }
 ```

-## Caveats
+### Caveats

 Some notes on the `start_date` and `end_date` query parameters:

@ -318,7 +320,7 @@ change the output you get from this endpoint. To get consistent information abou
 you must be sure to avoid updating rotations in-place but apply the changes as new rotations
 with the right starting dates.

-## Example script to transform data to .csv for all of your schedules
+### Example script to transform data to .csv for all of your schedules

 The following Python script will generate a `.csv` file, `oncall-report-2023-01-01-to-2023-01-31.csv`. This file will
 contain three columns, `user_pk`, `user_email`, and `hours_on_call`, which represents how many hours each user was
--- a/docs/sources/oncall-api-reference/shift_swaps.md
+++ b/docs/sources/oncall-api-reference/shift_swaps.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/shift_swaps/
-title: Shift swaps HTTP API
+title: Shift swap requests HTTP API
 weight: 1200
 ---

-# Create a shift swap request
+# Shift swap requests HTTP API
+
+## Create a shift swap request

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/" \
@ -77,7 +79,7 @@ The above command returns JSON structured in the following way:

 `POST {{API_URL}}/api/v1/shift_swaps/`

-# Get a shift swap request
+## Get a shift swap request

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \
@ -135,7 +137,7 @@ The above command returns JSON structured in the following way:

 `GET {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/`

-# List shift swap requests
+## List shift swap requests

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/" \
@ -195,7 +197,7 @@ The following available filter parameters may be provided as a `GET` arguments:

 `GET {{API_URL}}/api/v1/shift_swaps/`

-# Update a shift swap request
+## Update a shift swap request

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \
@ -259,7 +261,7 @@ The above command returns JSON structured in the following way:

 `PUT {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/`

-# Delete a shift swap request
+## Delete a shift swap request

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \
@ -272,7 +274,7 @@ curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \

 `DELETE {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/`

-# Take a shift swap request
+## Take a shift swap request

 ```shell
 curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/take" \
--- a/docs/sources/oncall-api-reference/slack_channels.md
+++ b/docs/sources/oncall-api-reference/slack_channels.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/slack_channels/
-title: Slack Channels HTTP API
+title: Slack channels HTTP API
 weight: 1300
 ---

-# List Slack Channels
+# Slack channels HTTP API
+
+## List Slack Channels

 ```shell
 curl "{{API_URL}}/api/v1/slack_channels/" \
--- a/docs/sources/oncall-api-reference/user_groups.md
+++ b/docs/sources/oncall-api-reference/user_groups.md
@ -1,12 +1,14 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/user_groups/
-title: OnCall User Groups HTTP API
+title: OnCall user groups HTTP API
 weight: 1400
 ---

 <!--Used in escalation policies with type = `notify_user_group` and in schedules.-->

-# List user groups
+# OnCall user groups HTTP API
+
+## List user groups

 ```shell
 curl "{{API_URL}}/api/v1/user_groups/" \
--- a/docs/sources/oncall-api-reference/users.md
+++ b/docs/sources/oncall-api-reference/users.md
@ -1,10 +1,12 @@
 ---
 canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/users/
-title: Grafana OnCall Users HTTP API
+title: Grafana OnCall users HTTP API
 weight: 1500
 ---

-# Get a user
+# Grafana OnCall users HTTP API
+
+## Get a user

 This endpoint retrieves the user object.

@ -50,7 +52,7 @@ Use `{{API_URL}}/api/v1/users/current` to retrieve the current user.
 | `timezone` |   No    | timezone of the user one of [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).                               |
 | `teams`    |   No    | List of team IDs the user belongs to                               |

-# List Users
+## List Users

 ```shell
 curl "{{API_URL}}/api/v1/users/" \