docs: split changelog into yearly pages for SEO/AEO (#29)

* docs: split changelog into yearly pages for SEO/AEO

Split the single 4,002-line changelog/index.mdx into 6 yearly pages
(2021-2026). The original index.mdx becomes a thin landing page linking
to each year.

- Create yearly pages: changelog/2021.mdx through changelog/2026.mdx
- Update sidebar config to list all yearly pages
- Add changelog to llms.txt custom sets (no longer excluded)
- Update update-changelog skill for yearly file targeting
- Update AFDocs known-exceptions for resolved page-size warning

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: polish changelog frontmatter descriptions

Reduce Warp repetition and include auto-update info.

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: address PR review — drop month ranges, remove auto-update claim

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>

Author: rachaelrenk

.agents/skills/afdocs-audit/references/known-exceptions.md

@@ -36,9 +36,9 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or
 
 ## page-size-markdown / page-size-html
 
-**Expected status**: warn — but only allowlist `/changelog/`
-**Reason**: The changelog page (`/changelog/`) is intentionally a single long page (~4,000 lines of MDX). It is excluded from `llms-full.txt` generation due to a `hast-util-to-text` stack overflow, but is still accessible at its URL and indexed by the sitemap.
-**Action**: If the only flagged page is `/changelog/`, classify as allowlisted. If other pages are flagged, treat those as genuine issues that may need splitting.
+**Expected status**: pass (after changelog split)
+**Reason**: The changelog was split into yearly pages in May 2026, resolving the page-size issue. No pages should flag this check now.
+**Action**: If any page is flagged, treat it as a genuine issue that may need splitting.
 
 ## section-header-quality
 

.agents/skills/update-changelog/SKILL.md

@@ -5,7 +5,7 @@ description: Update the public changelog at docs.warp.dev/changelog with the lat
 
 # Update Changelog
 
-Adds a new entry to `src/content/docs/changelog/index.mdx` for the latest stable Warp release, then opens a PR.
+Adds a new entry to the current year's changelog page (e.g. `src/content/docs/changelog/2026.mdx`) for the latest stable Warp release, then opens a PR.
 
 ## Related Skills
 
@@ -35,7 +35,23 @@ Parse it into components:
 
 ### Step 2: Check if already documented
 
-Read `src/content/docs/changelog/index.mdx` and search for the base version in existing `### ` header lines. If found, report that the changelog is already up to date and stop.
+Determine the year from the display date (e.g. `2026` from `2026.02.18`). The target file is `src/content/docs/changelog/{year}.mdx`.
+
+If the year file doesn't exist yet (year rollover), create it using this template:
+
+```markdown
+---
+title: "Changelog — {year}"
+description: >-
+  Warp release notes for {year}. Updates ship weekly, typically on Thursdays.
+---
+
+Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose)
+```
+
+Also update `src/content/docs/changelog/index.mdx` to add a link for the new year at the top of the list, and update `src/sidebar.ts` to add the new year entry.
+
+Read the target year file and search for the base version in existing `### ` header lines. If found, report that the changelog is already up to date and stop.
 
 ### Step 3: Fetch changelog data from `channel_versions.json` (primary source)
 
@@ -190,7 +206,7 @@ Reference the `2026.02.10` entry in the existing changelog for the exact `<figur
 
 ### Step 6: Insert into the changelog file
 
-Edit `src/content/docs/changelog/index.mdx`:
+Edit `src/content/docs/changelog/{year}.mdx` (the year file determined in Step 2):
 - Find the first line that starts with `### ` (this is the most recent existing entry)
 - Insert the new entry **immediately before** that line
 - Ensure there is exactly one blank line between the description paragraph ("Submit bugs and feature requests...") and the new entry's `### ` header
@@ -203,7 +219,7 @@ Edit `src/content/docs/changelog/index.mdx`:
 git checkout -b changelog/{base_version}
 
 # Stage and commit
-git add src/content/docs/changelog/index.mdx
+git add src/content/docs/changelog/
 git commit -m "docs: add changelog entry for {base_version}
 
 Co-Authored-By: Oz <oz-agent@warp.dev>"

astro.config.mjs

@@ -157,9 +157,7 @@ export default defineConfig({
 				// (excluded globally above — ~25k lines causes a stack overflow in hast-util-to-text).
 				{ label: 'Support', description: 'Troubleshooting, billing, and privacy.', paths: ['support-and-community/index', 'support-and-community/plans-and-billing/**', 'support-and-community/privacy-and-security/**', 'support-and-community/troubleshooting-and-support/**', 'support-and-community/community/contributing', 'support-and-community/community/open-source-partnership', 'support-and-community/community/refer-a-friend'] },
 					{ label: 'Guides', description: 'Task-oriented walkthroughs and tutorials.', paths: ['guides/**'] },
-					// Changelog excluded — the single page (4k lines) causes a stack overflow
-					// in hast-util-to-text during llms-full.txt generation. The page is still
-					// available at /changelog/ and indexed by the sitemap.
+					{ label: 'Changelog', description: 'Warp release notes by year.', paths: ['changelog/**'] },
 					],
 				}),
 			],