| 1 | # Recipe: rename a doc page |
| 2 | |
| 3 | Rename a page (change its display name in the sidebar / URL). |
| 4 | Functionally identical to a move because the URL slug is |
| 5 | derived from `meta.label`. Auto-redirected. |
| 6 | |
| 7 | ## 1. Edit map.yaml |
| 8 | |
| 9 | Open `<repo>/docs/.map/map.yaml`. Find the node and change |
| 10 | `meta.label`: |
| 11 | |
| 12 | ```yaml |
| 13 | # Before |
| 14 | - meta: |
| 15 | label: Old Name |
| 16 | edit_url: https://github.com/netdata/netdata/edit/master/docs/x/page.md |
| 17 | |
| 18 | # After |
| 19 | - meta: |
| 20 | label: New Name |
| 21 | edit_url: https://github.com/netdata/netdata/edit/master/docs/x/page.md |
| 22 | ``` |
| 23 | |
| 24 | `edit_url` stays unchanged (source file is still the same |
| 25 | file). |
| 26 | |
| 27 | ## 2. Optionally rename the source file too |
| 28 | |
| 29 | If you want the source file to also have a new name (cleaner), |
| 30 | rename it in this repo AND update `meta.edit_url` to match. |
| 31 | Two scenarios: |
| 32 | |
| 33 | - **Just label change**: edit_url unchanged. Auto-redirect |
| 34 | works; old URL maps to old GH URL maps (via the now-current |
| 35 | map) to new URL. |
| 36 | - **Label + source filename change**: edit_url changes. The |
| 37 | diff mechanism keys on edit_url, so the OLD edit_url is |
| 38 | what stores the redirect key. After the rename, the OLD |
| 39 | edit_url no longer points to a real source file in the |
| 40 | current commit -- but |
| 41 | `LegacyLearnCorrelateLinksWithGHURLs.json` still has it |
| 42 | pointing at the new URL via the previous-run snapshot. |
| 43 | This works for ONE rename cycle. If you rename again later, |
| 44 | the chain may break -- so prefer to keep edit_url stable. |
| 45 | |
| 46 | ## 3. Test locally |
| 47 | |
| 48 | ```bash |
| 49 | cd ${NETDATA_REPOS_DIR}/learn |
| 50 | . venv/bin/activate |
| 51 | python3 ingest/ingest.py --local-repo netdata:<repo> \ |
| 52 | --ignore-on-prem-repo --fail-links-netdata |
| 53 | ``` |
| 54 | |
| 55 | Check that the auto-redirect is generated. See |
| 56 | `../redirects.md`. |
| 57 | |
| 58 | ## 4. Open the docs PR |
| 59 | |
| 60 | map.yaml change (and source file rename if applicable). |
| 61 | Reviewers check the `edit_url` regex and that the rename |
| 62 | makes sense. |
| 63 | |
| 64 | ## 5. After merge |
| 65 | |
| 66 | Same flow as move/add: 0-3 hour cron + ingest PR + manual |
| 67 | merge + Netlify deploy. |
| 68 | |
| 69 | ## 6. Verify |
| 70 | |
| 71 | ```bash |
| 72 | # Old URL redirects to new |
| 73 | curl -sI https://learn.netdata.cloud<old-path> # expect 301 |
| 74 | # New URL works |
| 75 | curl -sI https://learn.netdata.cloud<new-path> # expect 200 |
| 76 | ``` |
| 77 | |
| 78 | ## Notes |
| 79 | |
| 80 | - **Slug computation refresher**: the slug = lowercase |
| 81 | `<learn_rel_path>/<sanitized-label>`, with spaces -> `-`, |
| 82 | `//` -> `/`. So `Old Name` -> `old-name`, `New Name` -> |
| 83 | `new-name`. |
| 84 | - **The filename in the learn repo also changes** because the |
| 85 | destination filename is derived from `sidebar_label` (with |
| 86 | case preserved + only certain chars stripped). So |
| 87 | `${NETDATA_REPOS_DIR}/learn/docs/x/Old Name.mdx` becomes |
| 88 | `New Name.mdx`. This is normal and ingest handles it. |
| 89 | - **External links to the OLD URL keep working** thanks to |
| 90 | the auto-redirect. But it's still good practice to update |
| 91 | any first-party references (within |
| 92 | `<repo>/docs/...`). |
| 93 | |
| 94 | ## Common mistakes |
| 95 | |
| 96 | - **Renaming `meta.label` to something with `/`, `(`, `)`, |
| 97 | `,`, `'`, backtick, or `:`** -- those characters get |
| 98 | stripped by the slug sanitizer. Pick a label that survives |
| 99 | cleanup. |
| 100 | - **Forgetting that the URL changes.** A rename IS a URL |
| 101 | change. The auto-redirect mitigates external link breakage, |
| 102 | but the URL surface itself moves. |
| 103 | - **Renaming a page with `slug:` override in source |
| 104 | frontmatter.** The auto-redirect mechanism is bypassed |
| 105 | (slug override wins). You'll need manual JSON surgery |
| 106 | similar to the delete recipe. |