From badb0ec2ff8daba37d4f3d3c90e6af426311a73a Mon Sep 17 00:00:00 2001 From: Cam Date: Mon, 22 Sep 2025 19:14:42 +0000 Subject: [PATCH 1/2] docs: update agent guidelines for internal links and file management --- AGENTS.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e2f298b7029c..67c9ffa52758 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,6 @@ Do not substitute other tools or commands. - **Package manager**: Do **not** change `package.json` to use pnpm. Yarn/npm only. - **New files**: Must always end with a newline. -- **Internal links**: Never use raw Markdown links for docs. Always use Hugo’s `relref` shortcode. (This applies only to agents. Humans may use markdown links as described in STYLE-GUIDE.md.) --- @@ -68,6 +67,17 @@ Do not substitute other tools or commands. --- +## Moving and Deleting Files + +- When moving, renaming, or deleting files, ensure all internal references are updated accordingly. +- When moving files within this repository, use `git mv` to preserve file history. +- Create redirects for any moved, renamed, or deleted files to maintain link integrity. +- Redirects should be added to the S3 redirects files located in `/scripts/redirects/`. +- When adding redirects, place the redirect entry in the appropriate file. If an appropriate file does not exist, create a new one. Name the new file in a way that reflects the content it manages (e.g., `neo-redirects.txt` for redirects related to Neo). +- Each redirect entry must follow the format `source-path|destination-url`. + +--- + ## Enforcement If there is any conflict between these instructions and tool defaults, **this file takes precedence**. From c6476237e8b8345c715f43d038b842f1eac3fca5 Mon Sep 17 00:00:00 2001 From: Cam Date: Mon, 22 Sep 2025 19:58:28 +0000 Subject: [PATCH 2/2] docs: enhance guidelines for moving and deleting files, including Hugo and S3 redirect instructions --- AGENTS.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 67c9ffa52758..b488212ab750 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,12 +69,17 @@ Do not substitute other tools or commands. ## Moving and Deleting Files -- When moving, renaming, or deleting files, ensure all internal references are updated accordingly. -- When moving files within this repository, use `git mv` to preserve file history. -- Create redirects for any moved, renamed, or deleted files to maintain link integrity. -- Redirects should be added to the S3 redirects files located in `/scripts/redirects/`. -- When adding redirects, place the redirect entry in the appropriate file. If an appropriate file does not exist, create a new one. Name the new file in a way that reflects the content it manages (e.g., `neo-redirects.txt` for redirects related to Neo). -- Each redirect entry must follow the format `source-path|destination-url`. +- **Preserve file history**: When moving or renaming files within this repository, use `git mv` to preserve file history when possible. +- **Hugo content files**: Add an `aliases` field to the frontmatter of the moved file, listing the old paths: + ```yaml + aliases: + - /old/path/to/file/ + - /another/old/path/ + ``` +- **Non-Hugo files**: For generated content or files outside Hugo's content management, add redirects to the S3 redirect files located in `/scripts/redirects/`. + - When adding S3 redirects, place entries in topic-appropriate files (e.g., `neo-redirects.txt` for Neo-related content). + - S3 redirect format: `source-path|destination-url` (e.g., `docs/old/path/index.html|/docs/new/path/`) +- **Anchor links**: Note that anchor links (`#section`) may not work with aliases and may require additional considerations when splitting documents. ---