# Recipe: delete (unpublish) a doc page

The only recipe that requires **manual surgery** in the learn
repo. Deletion does NOT auto-redirect -- without the manual
step, the old URL serves a 404.

The canonical reference for this recipe is
`<repo>/docs/.map/README.md:96-104`.

## 1. Decide where deleted-link traffic should go

Before deleting, decide one of:

- **Redirect to a closest replacement page.** Best for SEO
  and external link preservation. Pick a page whose content
  largely replaces the deleted one.
- **Drop the link entirely (404).** Acceptable for pages with
  little inbound traffic that have no good replacement.

You'll apply the decision in step 4.

## 2. Delete the source file and remove the map.yaml node

In this repo:

1. Delete the source `.md` file.
2. Open `<repo>/docs/.map/map.yaml` and remove the matching
   node.
3. Open the docs PR.

After this PR merges, ingest's next run produces a "Ingest
New Documentation" PR in the learn repo that DOES NOT
auto-redirect the old URL (because the GH source URL no
longer points to a real file, the `UpdateGHLinksBasedOnMap`
step can't resolve it).

## 3. Open the learn-repo manual-surgery PR

Once the ingest PR is merged (or BEFORE if you want to bundle
the surgery with the ingest PR -- see step 4 alternative):

1. Open `${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json`.
2. Search for the GitHub blob/edit URL of the deleted file:
   ```
   "https://github.com/netdata/netdata/blob/master/docs/<...>/<deleted-page>.md"
   ```
3. Find the entry. Apply your decision from step 1:
   - **Redirect to replacement**: change the value to the
     full Learn URL of the replacement page
     (`https://learn.netdata.cloud/docs/<replacement>`).
   - **Drop**: delete the entry from the JSON entirely.

Save the file.

Alternative: if you want a one-off manual `[[redirects]]`
rule (for example, to redirect to an entirely external
domain), edit `${NETDATA_REPOS_DIR}/learn/static.toml` and
add a hand-rolled entry under `# section: static`. This
gets copied into `netlify.toml` on the next ingest.

## 4. Open a learn-repo PR

Title: `manual redirect surgery for deleted page <name>`. PR
body explains what was deleted, where the redirect goes, and
why.

## 5. Merge and verify

After Netlify deploys:

```bash
# If you redirected to replacement:
curl -sI https://learn.netdata.cloud<old-path>
# Expect: HTTP/2 301
# Location: https://learn.netdata.cloud<replacement-path>

# If you dropped:
curl -sI https://learn.netdata.cloud<old-path>
# Expect: HTTP/2 404
```

## Notes

- **Daily link checker**: the daily
  `${NETDATA_REPOS_DIR}/learn/.github/workflows/daily-learn-link-check.yml`
  cron will start failing if it finds a `learn_link:`
  pointing at the deleted page. To minimize noise, do step 3
  promptly after step 2.

- **Internal links from other Learn pages**: search
  `${NETDATA_REPOS_DIR}/learn/docs/` and this repo's `<repo>/docs/`
  for explicit links to the deleted page's URL and update them.
  The link rewriter (step 12 of the ingest pipeline) will
  flag broken internal links during ingest if you missed any.

- **If you re-publish later**: the redirect entry can stay
  in `LegacyLearnCorrelateLinksWithGHURLs.json`. The
  `UpdateGHLinksBasedOnMap` step will re-resolve the GH URL
  through the new map and route the old URL to the new
  destination automatically. So if you later add a similar
  page back, the old URL keeps working with no further
  surgery.

## Common mistakes

- **Forgetting the manual JSON surgery.** Without it, the
  deleted page's old URL serves a 404. External links break
  silently for users.
- **Editing `netlify.toml` directly.** Regenerated each
  ingest. Edit `static.toml` (for hand-curated static rules)
  or `LegacyLearnCorrelateLinksWithGHURLs.json` (for the
  dynamic catalog).
- **Deleting a `part_of_learn: True` page.** That's a
  hand-authored learn-repo page (currently only
  `docs/ask-nedi.mdx`). Deleting it requires editing the
  learn repo directly, NOT this repo's map.yaml. And the
  home page redirects to it -- removing it breaks the site
  root.
- **Deleting an integration page.** Integration pages are
  generated by the integrations pipeline. Don't delete the
  generated `.md` directly. Edit the source `metadata.yaml`
  to remove the integration (or change its category) -- see
  the `integrations-lifecycle` skill.
