Handbook: delete page or section

Scope

Applies to cortex-hub handbook/ — Nuxt Content collection docs (content.config.ts: source.include: 'docs/**', prefix: '/docs').

Skills under content/skills/** use /skills/… paths; use a separate workflow for those.

Map URL ↔ file

1. Public path (with trailing slash in the browser): /docs/<segments>/<slug>/
2. On disk: handbook/content/docs/<ordered-folder>/<ordered-file>.md
3. Ordering prefixes (\d+.) on folder and file names are stripped for routing. Example:
   • File: content/docs/2.infrastructure/6.terraform-repository-layout.md
   • URL: /docs/infrastructure/terraform-repository-layout/

Index-style pages often use 0.overview.md → last segment overview (e.g. /docs/infrastructure/overview/).

If the user gives a full URL (e.g. http://localhost:3000/docs/...), strip origin and optional locale segment; normalize to /docs/... for searching.

Workflow

1. Identify targets

• Single page: the .md file(s) to delete.
• Whole subsection: directory under content/docs/<N>.section-name/ (all .md files + .navigation.yml if present).

Confirm there is no replacement target yet (or plan redirects — see below).

2. Delete content

• Remove the page file(s) and, for a section, the folder.
• If the section had .navigation.yml, remove it with the folder.

3. Find and fix references

Search from repo root cortex-hub/handbook (and optionally whole cortex-hub if links could live outside handbook/).

Kind	How to find	What to do
Markdown links	Ripgrep: path segment or full path, e.g. terraform-repository-layout, /docs/infrastructure/terraform-repository-layout	Remove sentence/link, or point to the replacement page
Frontmatter links grids (to: /docs/...)	Same grep; common in 0.overview.md, content/index.md, onboarding pages	Remove the entry or retarget to
Legacy redirects	handbook/layers/legacy-redirects/nuxt.config.ts — keys under routeRules that redirect to the removed URL, or old /engineering/... paths that pointed at it	Remove those rules. If external bookmarks matter, add a new rule from the old path to a surviving doc instead of leaving a dead target
Cross-references in same section	Grep the slug and the human title of the page	Update “see also” prose

Use patterns that catch trailing-slash variants and markdown parentheses:

• docs/.../slug
• /docs/.../slug

Re-run grep until zero stale hits remain for that path (except intentional redirect comments if any).

4. Optional: redirect instead of 404

If the topic moved to another page, keep a routeRules entry in legacy-redirects/nuxt.config.ts from the old path to the new /docs/... path (with and without trailing / if the file uses both patterns). Do not redirect to a deleted URL.

5. Verify

• No broken links: grep clean for old path.
• Run handbook build or dev preview if available; open former URL and confirm 404 or redirect as intended.

Removing only a heading “section”

If the user means a heading block inside one .md file: delete that block only, then grep for anchor links to #... that targeted that heading and update or remove them.

Renumbering files

Renaming N. prefixes is optional; ordering uses those prefixes. Only renumber if the team cares about contiguous ordering after deletion — never required for routing.

Checklist (copy for the agent)

- [ ] Deleted content file(s) or section folder under content/docs/
- [ ] Grep-fixed markdown + frontmatter links to old /docs/ path
- [ ] Updated or removed legacy-redirects routeRules targeting removed URL
- [ ] Re-grep: no stale references to old path
- [ ] Confirmed replacement or404 behavior in browser/build