| 1 | # Recipe: delete (unpublish) a doc page |
| 2 | |
| 3 | The only recipe that requires **manual surgery** in the learn |
| 4 | repo. Deletion does NOT auto-redirect -- without the manual |
| 5 | step, the old URL serves a 404. |
| 6 | |
| 7 | The canonical reference for this recipe is |
| 8 | `<repo>/docs/.map/README.md:96-104`. |
| 9 | |
| 10 | ## 1. Decide where deleted-link traffic should go |
| 11 | |
| 12 | Before deleting, decide one of: |
| 13 | |
| 14 | - **Redirect to a closest replacement page.** Best for SEO |
| 15 | and external link preservation. Pick a page whose content |
| 16 | largely replaces the deleted one. |
| 17 | - **Drop the link entirely (404).** Acceptable for pages with |
| 18 | little inbound traffic that have no good replacement. |
| 19 | |
| 20 | You'll apply the decision in step 4. |
| 21 | |
| 22 | ## 2. Delete the source file and remove the map.yaml node |
| 23 | |
| 24 | In this repo: |
| 25 | |
| 26 | 1. Delete the source `.md` file. |
| 27 | 2. Open `<repo>/docs/.map/map.yaml` and remove the matching |
| 28 | node. |
| 29 | 3. Open the docs PR. |
| 30 | |
| 31 | After this PR merges, ingest's next run produces a "Ingest |
| 32 | New Documentation" PR in the learn repo that DOES NOT |
| 33 | auto-redirect the old URL (because the GH source URL no |
| 34 | longer points to a real file, the `UpdateGHLinksBasedOnMap` |
| 35 | step can't resolve it). |
| 36 | |
| 37 | ## 3. Open the learn-repo manual-surgery PR |
| 38 | |
| 39 | Once the ingest PR is merged (or BEFORE if you want to bundle |
| 40 | the surgery with the ingest PR -- see step 4 alternative): |
| 41 | |
| 42 | 1. Open `${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json`. |
| 43 | 2. Search for the GitHub blob/edit URL of the deleted file: |
| 44 | ``` |
| 45 | "https://github.com/netdata/netdata/blob/master/docs/<...>/<deleted-page>.md" |
| 46 | ``` |
| 47 | 3. Find the entry. Apply your decision from step 1: |
| 48 | - **Redirect to replacement**: change the value to the |
| 49 | full Learn URL of the replacement page |
| 50 | (`https://learn.netdata.cloud/docs/<replacement>`). |
| 51 | - **Drop**: delete the entry from the JSON entirely. |
| 52 | |
| 53 | Save the file. |
| 54 | |
| 55 | Alternative: if you want a one-off manual `[[redirects]]` |
| 56 | rule (for example, to redirect to an entirely external |
| 57 | domain), edit `${NETDATA_REPOS_DIR}/learn/static.toml` and |
| 58 | add a hand-rolled entry under `# section: static`. This |
| 59 | gets copied into `netlify.toml` on the next ingest. |
| 60 | |
| 61 | ## 4. Open a learn-repo PR |
| 62 | |
| 63 | Title: `manual redirect surgery for deleted page <name>`. PR |
| 64 | body explains what was deleted, where the redirect goes, and |
| 65 | why. |
| 66 | |
| 67 | ## 5. Merge and verify |
| 68 | |
| 69 | After Netlify deploys: |
| 70 | |
| 71 | ```bash |
| 72 | # If you redirected to replacement: |
| 73 | curl -sI https://learn.netdata.cloud<old-path> |
| 74 | # Expect: HTTP/2 301 |
| 75 | # Location: https://learn.netdata.cloud<replacement-path> |
| 76 | |
| 77 | # If you dropped: |
| 78 | curl -sI https://learn.netdata.cloud<old-path> |
| 79 | # Expect: HTTP/2 404 |
| 80 | ``` |
| 81 | |
| 82 | ## Notes |
| 83 | |
| 84 | - **Daily link checker**: the daily |
| 85 | `${NETDATA_REPOS_DIR}/learn/.github/workflows/daily-learn-link-check.yml` |
| 86 | cron will start failing if it finds a `learn_link:` |
| 87 | pointing at the deleted page. To minimize noise, do step 3 |
| 88 | promptly after step 2. |
| 89 | |
| 90 | - **Internal links from other Learn pages**: search |
| 91 | `${NETDATA_REPOS_DIR}/learn/docs/` and this repo's `<repo>/docs/` |
| 92 | for explicit links to the deleted page's URL and update them. |
| 93 | The link rewriter (step 12 of the ingest pipeline) will |
| 94 | flag broken internal links during ingest if you missed any. |
| 95 | |
| 96 | - **If you re-publish later**: the redirect entry can stay |
| 97 | in `LegacyLearnCorrelateLinksWithGHURLs.json`. The |
| 98 | `UpdateGHLinksBasedOnMap` step will re-resolve the GH URL |
| 99 | through the new map and route the old URL to the new |
| 100 | destination automatically. So if you later add a similar |
| 101 | page back, the old URL keeps working with no further |
| 102 | surgery. |
| 103 | |
| 104 | ## Common mistakes |
| 105 | |
| 106 | - **Forgetting the manual JSON surgery.** Without it, the |
| 107 | deleted page's old URL serves a 404. External links break |
| 108 | silently for users. |
| 109 | - **Editing `netlify.toml` directly.** Regenerated each |
| 110 | ingest. Edit `static.toml` (for hand-curated static rules) |
| 111 | or `LegacyLearnCorrelateLinksWithGHURLs.json` (for the |
| 112 | dynamic catalog). |
| 113 | - **Deleting a `part_of_learn: True` page.** That's a |
| 114 | hand-authored learn-repo page (currently only |
| 115 | `docs/ask-nedi.mdx`). Deleting it requires editing the |
| 116 | learn repo directly, NOT this repo's map.yaml. And the |
| 117 | home page redirects to it -- removing it breaks the site |
| 118 | root. |
| 119 | - **Deleting an integration page.** Integration pages are |
| 120 | generated by the integrations pipeline. Don't delete the |
| 121 | generated `.md` directly. Edit the source `metadata.yaml` |
| 122 | to remove the integration (or change its category) -- see |
| 123 | the `integrations-lifecycle` skill. |