add-redirects

name	add-redirects
description	Add redirects when MongoDB documentation pages are renamed, moved, or deleted under content/. Use this skill when page .txt files are renamed/moved/deleted in content/*/source/.

Add Redirects for MongoDB Docs

When a published documentation page is renamed, moved, or deleted, the old URL must continue to resolve. This skill classifies pending page changes and adds the appropriate [[redirects]] entries to the project's netlify.toml.

When this skill applies

Add redirects when a .txt page has been renamed, moved, or deleted from:

• content/<project>/<version>/source/ (versioned projects)
• content/<project>/source/ (unversioned projects such as atlas or compass)

Do not trigger for files under any of these paths:

• includes/ — include files and YAML snippets
• images/ — image assets
• content/code-examples/tested/ — canonical Grove-tested snippets (repo root)
• source/code-examples/ — per-project symlink to Grove-tested snippets
• includes/code-examples/ — product-specific non-Grove example scripts

Also do not add redirects for:

• Typo fixes inside an existing redirect entry.
• New pages that do not replace a previous URL.

Step 1: Enumerate the pending changes

Run two commands and combine the results — do not rely on only one:

# All changes on this branch vs main (committed or not)
git diff --name-status origin/main...HEAD

# Uncommitted changes not yet in any commit
git diff --name-status HEAD

Filter both outputs to .txt files under content/<project>/source/, excluding /includes/. Deduplicate. This is the complete set of page changes that need redirects — do not limit to only the most recent commit.

Also list untracked new .txt pages with:

git ls-files --others --exclude-standard 'content/*/source/**/*.txt'

Classify each entry:

Status	Meaning	Redirect action
R<score> old new	Rename (git-detected)	Deterministic: old URL → new URL
D path	Delete	Ambiguous — ask user for target
A path	Addition	Usually none; ask if it replaces a deleted page
Untracked new file	Addition	Same as A

Cross-project move detection: Before treating a D as an ambiguous delete, check whether any A entry in a different project shares the same filename and a similar relative path. If so, flag it to the user as a probable cross-project move (e.g., a page moved from content/atlas/ to content/atlas-vector-search/) and confirm the redirect target before writing anything. Do not assume the match is correct — the user must confirm.

For any ambiguous case (D, or suspected manual rename that git didn't detect), stop and ask the user before writing the redirect. Present a maximum of three options (e.g., parent page / sibling page / catch-all).

Handle all changes in one pass. List every pending deletion/rename to the user upfront, collect all redirect targets, then write all entries at once. Do not process one file and stop.

Build paradigm

MongoDB documentation projects use two different build types:

• snooty-based projects, legacy (e.g., manual, compass) use netlify.toml for redirects.
• next.js-based projects (e.g., atlas) use a per-project JSON file for redirects.

Next.js projects store redirects in one of two locations, depending on migration progress:

• platform/docs-site/src/redirects/<project>-redirects.json — the new SSG app. Projects migrated to docs-site live here.
• platform/docs-nextjs/src/redirects/<project>-redirects.json — the legacy Next.js app. Projects not yet migrated live here.

A given project appears in only one of these locations, never both. Check docs-site first; if the file exists there, the project has migrated and that is the file to update. If not, check docs-nextjs.

This skill must check for the presence of netlify.toml and the project's JSON redirect file for every content site that contains changes. If netlify.toml exists, update the project's netlify.toml file and the JSON redirect file (whichever location exists). If netlify.toml does not exist, update only the JSON file.

Run this command to check for netlify.toml for each project with renamed / deleted / added .txt files:

ls content/<project>/netlify.toml 2>/dev/null

Run these commands to locate the project's JSON redirect file (check docs-site first, then docs-nextjs):

ls platform/docs-site/src/redirects/<project>-redirects.json 2>/dev/null
ls platform/docs-nextjs/src/redirects/<project>-redirects.json 2>/dev/null

Sections below contain references for updating redirects for both paradigms. The general process is the same, but the file format and insertion point differ.

Directory-move detection (do this before resolving individual URLs)

After listing all renames, check whether any group of renames represents a whole-directory move. A directory move has occurred when:

1. All renames in the group share the same source directory prefix (the path up to the deepest common directory component), AND
2. All renames in the group share the same destination directory prefix, AND
3. The relative filenames are preserved (each file's name is identical in source and destination).

If those three conditions hold for a group of four or more files, use a splat wildcard instead of individual entries. For groups of three or fewer renames, write individual entries even if all three conditions are met — small moves are more readable and precise as explicit entries, and a splat is not worth the generality for two or three URLs.

For unversioned projects: load references/non-version-directory-change-toml.md for toml example. Load references/non-version-directory-change.json for JSON example.

For versioned projects: load references/version-directory-change-toml.md for toml example. Load references/version-directory-change-json.md for JSON example.

Do not write entries for EOL versions.

If the directory move only partially applies (some files in the source directory were not renamed), do not use a splat or path wildcard — write individual entries for each renamed file only.

Step 2: Resolve file path → URL

File paths map to URLs via the project's snooty.toml. For versioned projects, each version has its own snooty.toml at content/<project>/<version>/snooty.toml; read the one for the version being changed. For unversioned projects, read content/<project>/snooty.toml. In both cases, look for:

• name — a hint at the project slug, but not always equal to the URL segment. Some projects use a different value (e.g., Atlas has name = "cloud-docs" but serves at /docs/atlas/).
• url — the production URL base (sanity check only).

General mapping:

content/<project>/<version>/source/<path>/<name>.txt
  →  /docs/<project-slug>/<version-segment>/<path>/<name>/

Where <version-segment> depends on the project's directory naming convention:

• current/ often maps to no version segment or to the default version alias.
• v8.0/ maps to v8.0.
• upcoming/ maps to upcoming.

Special case — MongoDB Manual: The manual uses a nested directory structure. content/manual/manual/ is the "current" release and maps to /docs/manual/ (no version segment). content/manual/upcoming/ maps to /docs/upcoming/, and content/manual/v8.0/ maps to /docs/v8.0/. When working in content/manual/manual/, use /docs/manual/ as the URL base, not /docs/manual/manual/.

The netlify.toml and -redirects.json are authoritative. If present, open the project's netlify.toml and read the URL shape from existing [[redirects]] entries — use that shape exactly. Do not rely solely on name from snooty.toml; treat it as a starting guess only. Do not invent a URL pattern the project does not already use. If netlify.toml is absent, rely on URL shape from objects in <project>-redirects.json.

Non-versioned projects (e.g., atlas, compass) have a single source/ at the project root; the path maps directly with no version segment.

Step 3: Find the insertion point

netlify.toml

Each project's netlify.toml lives at content/<project>/netlify.toml (outside version folders). It is divided into labeled sections, typically in this order:

1. Metadata / build config
2. # OFFLINE REDIRECTS
3. # ALIAS REDIRECTS
4. # WILDCARD REDIRECTS
5. # PAGE-SPECIFIC REDIRECTS — usually subdivided by version (## current, ## v8.0, ## v7.0)
6. # CATCH ALLS — must remain last

Insert new page-level redirects in the PAGE-SPECIFIC REDIRECTS section, under the matching version heading. Place more-specific entries above more-general ones. Never move or edit the CATCH ALLS block.

If the file has no section markers, append new entries at the end of the file — but before any # CATCH ALLS block if one exists. Never insert after the CATCH ALLS.

-redirects.json

Each project's JSON file lives at platform/docs-site/src/redirects/<project>-redirects.json (migrated projects) or platform/docs-nextjs/src/redirects/<project>-redirects.json (legacy projects) — whichever you located in the Build paradigm step. Both use the same format: a flat array of objects with source and destination fields. Insert new entries at the end of the array. Do not reorder existing entries or create duplicate entries.

Step 4: Write the redirect entry

The standard form toml form is found in references/standard-redirect-form-toml.md. The standard JSON form is found in references/standard-redirect-form-json.md.

For versioned projects, complete Step 5 before writing entries — the wildcard vs. per-version decision must be made first.

Step 5: Handle versioned and backported changes

When renames or deletes appear in multiple version directories of the same project, determine whether a wildcard or per-version entries are correct before writing anything.

Determine the active versions

Read the project's snooty.toml for each version. If eol = true, the version is end-of-life — do not write redirects for them.

Wildcard vs. per-version decision

Group the changed files by their relative path (the part after source/). For each group:

All active versions affected → use a :version wildcard (one entry covers all): load references/all-versions-affected-toml.md for toml example. Load references/all-versions-affected.json for JSON example.

Do not also write per-version entries for the same path — that creates duplicates.

Only some active versions affected → write one entry per affected version

• netlify.toml: each under its respective ## <version> subheading in PAGE-SPECIFIC REDIRECTS. Use the hardcoded version in the path (e.g., /docs/v8.0/...), not :version.
• JSON: Use the hardcoded version in the path (e.g., /docs/v8.0/...), not :version.

A wildcard redirect already covers the old path → no new entry needed. If an existing from = "/docs/:version/<old-path>/*" or source = "/docs/:version/:path*" already resolves to the right destination, skip.

If the change was only backported to some versions, redirects may also be needed in the opposite direction on versions that did not move — confirm with the user before writing reverse redirects.

Step 6: Validate

• Self-redirect check: from and to or source and destination must not be equal.
• Chain check: the to or source target must not itself appear as a from or destination elsewhere in the file (the CI Redirect Linter will block either case).
• Ordering check: (for netlify.toml files only) new entries are above CATCH ALLS and in a reasonable spot relative to more-general wildcards.
• Style check: indentation and field order match the surrounding entries.

Step 7: Regenerate docs-site redirect aggregates (docs-site only)

If the project's JSON redirect file is in platform/docs-site/src/redirects/ (i.e., the project has migrated to docs-site), you must regenerate the aggregate files after editing the per-project JSON. Skip this step entirely for docs-nextjs or netlify.toml-only changes.

Why this matters: docs-site serves soft redirects (page renames, no force: true) from a generated flat aggregate — all-redirects.json — read directly by the Netlify edge function at request time. The per-project JSON files are not read at runtime for soft redirects; only the aggregate is. If you edit compass-redirects.json but do not regenerate, the redirect will never fire in production — the old URL returns a 404 with no error anywhere in the pipeline. docs-nextjs does not have this aggregate, so the step is not needed there.

Run from platform/docs-site/:

pnpm generate:redirects

This regenerates two auto-generated files — src/redirects/all-redirects.ts (static-import barrel for the Next.js app) and src/redirects/all-redirects.json (flattened data array for the edge function). Do not hand-edit either file; always regenerate via the script.

Include both regenerated files in the PR alongside the edited per-project JSON. Verify with git status that only all-redirects.ts and all-redirects.json changed (beyond your intended edits) — if other files show unexpected changes, investigate before committing.

Step 8: Summarize and hand off

Report to the user:

• Each change detected and how it was classified.
• Each redirect block added, with its destination section and version.
• Any ambiguities that required user confirmation.
• Any cases where no redirect was needed and why.
• Whether all-redirects.ts and all-redirects.json were regenerated (docs-site projects only), and a reminder to include them in the commit.