@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 106 lines 3.26 KB
Rendered Raw
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.