ContextQMD
Back to Netdata

Recipe: delete (unpublish) a doc page

.agents/skills/learn-site-structure/recipes/delete-doc-page.md

2.11.04.3 KB
Original Source

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.

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.