| 1 | # Recipe: move a doc page (different sidebar location) |
| 2 | |
| 3 | Move a page from one sidebar location to another. The source |
| 4 | file stays where it is; only its position in `map.yaml` |
| 5 | changes. Ingest auto-generates a redirect from the old URL to |
| 6 | the new one. |
| 7 | |
| 8 | ## 0. Pre-check |
| 9 | |
| 10 | Confirm the page is a regular doc (`.md`), not an integration |
| 11 | page. Integration pages flow through the integrations |
| 12 | pipeline; their position is driven by their `meta.categories`, |
| 13 | not by `map.yaml`. To move an integration page, you change |
| 14 | the integration's category in its `metadata.yaml` (see the |
| 15 | `integrations-lifecycle` skill). |
| 16 | |
| 17 | ## 1. Edit map.yaml |
| 18 | |
| 19 | Open `<repo>/docs/.map/map.yaml`. |
| 20 | |
| 21 | 1. Find the existing node for the page. |
| 22 | 2. Cut it from the old location and paste it under the new |
| 23 | parent. |
| 24 | 3. Keep `meta.edit_url` UNCHANGED -- it still points to the |
| 25 | same source file. |
| 26 | 4. Optionally adjust `meta.label` if the new location calls |
| 27 | for a different display name (this changes the URL slug |
| 28 | too -- in that case it's effectively also a rename). |
| 29 | |
| 30 | ## 2. Test locally |
| 31 | |
| 32 | ```bash |
| 33 | cd ${NETDATA_REPOS_DIR}/learn |
| 34 | . venv/bin/activate |
| 35 | python3 ingest/ingest.py --local-repo netdata:<repo> \ |
| 36 | --ignore-on-prem-repo --fail-links-netdata |
| 37 | ``` |
| 38 | |
| 39 | Check: |
| 40 | - The page appears under the new parent in the sidebar. |
| 41 | - A redirect entry was added to `netlify.toml` and |
| 42 | `LegacyLearnCorrelateLinksWithGHURLs.json` from the old URL |
| 43 | to the new target. |
| 44 | |
| 45 | ```bash |
| 46 | grep -A1 "<old-url>" netlify.toml LegacyLearnCorrelateLinksWithGHURLs.json |
| 47 | ``` |
| 48 | |
| 49 | ## 3. Open the docs PR |
| 50 | |
| 51 | Single map.yaml change. The source `.md` file is unchanged. |
| 52 | |
| 53 | ## 4. After merge |
| 54 | |
| 55 | Same as add-doc-page: 0-3 hour cron + ingest PR + manual |
| 56 | merge + Netlify deploy. The auto-generated redirect ships |
| 57 | with the ingest PR. |
| 58 | |
| 59 | ## 5. Verify |
| 60 | |
| 61 | After deploy: |
| 62 | - The page is at the new URL. |
| 63 | - The OLD URL redirects to the new one (HTTP 301 from |
| 64 | Netlify edge). |
| 65 | |
| 66 | ```bash |
| 67 | curl -sI https://learn.netdata.cloud<old-path> |
| 68 | # Expect: HTTP/2 301 |
| 69 | # Location: https://learn.netdata.cloud<new-path> |
| 70 | ``` |
| 71 | |
| 72 | ## Notes |
| 73 | |
| 74 | - **Auto-redirect is via the GitHub blob URL**, not via the |
| 75 | old Learn URL directly. The catalog is anchored to |
| 76 | `github.com/netdata/netdata/blob/master/<source-path>` so |
| 77 | multiple consecutive moves keep working as long as the |
| 78 | source file still exists. |
| 79 | |
| 80 | - **If you also rename the file in source**, treat that as a |
| 81 | separate move + you must update `meta.edit_url`. The diff |
| 82 | mechanism still works because the OLD `meta.edit_url` value |
| 83 | is what gets stored as the redirect's GH URL key. |
| 84 | |
| 85 | - **`slug:` overrides bypass the diff mechanism.** If the |
| 86 | page has a frontmatter `slug:`, moving the map.yaml row |
| 87 | does NOT change the URL, so no redirect is generated. To |
| 88 | move a slug-override page, edit the slug AND ensure a |
| 89 | manual entry lands in |
| 90 | `LegacyLearnCorrelateLinksWithGHURLs.json` (similar to the |
| 91 | delete recipe). |
| 92 | |
| 93 | ## Common mistakes |
| 94 | |
| 95 | - **Editing `meta.edit_url` when only moving.** The edit_url |
| 96 | should NOT change for a move (the source file stays put). |
| 97 | - **Editing the source file path AND the map.yaml row in the |
| 98 | same PR without updating `meta.edit_url`.** Will produce |
| 99 | validation failures because the schema regex requires the |
| 100 | edit_url to match an existing source file. |
| 101 | - **Expecting the OLD URL to disappear.** It auto-redirects |
| 102 | forever. Don't break links pointing to it. |