Reorganize Articles into year/month page bundles

[HeyItsGilbert]

Problem Statement

As the Article archive grows, a single flat content collection is difficult to navigate and cannot co-locate an Article with its media. The site needs a source hierarchy organized by publication year and month while retaining every published Article URL, WordPress-era alias, Author taxonomy relationship, and current site behavior.

Solution

Organize Articles beneath year and month branch bundles, and represent each Article as a leaf bundle with its Markdown entry point and optional page resources. Preserve each Article's established dated public URL with an explicit full-path URL override. Keep the root Article archive as a chronological, paginated listing of all Articles; provide year and month archive pages; and retain the present Article page presentation, taxonomy behavior, feeds, SEO metadata, and existing static media until media is migrated deliberately.

User Stories

1. As a site visitor, I want every existing Article URL to continue resolving, so that saved links and search results remain valid.
2. As a site visitor, I want historic WordPress-era Article aliases to continue redirecting, so that older external references remain useful.
3. As a site visitor, I want the Articles archive to show all Articles in chronological order, so that I can discover content without knowing its publication date.
4. As a site visitor, I want pagination on the Articles archive to behave as it does today, so that browsing a large archive remains manageable.
5. As a site visitor, I want a year archive, so that I can browse Articles from a specific year.
6. As a site visitor, I want a month archive within a year, so that I can narrow a historical search by publication period.
7. As a site visitor, I want an Article page to retain its current presentation, so that the reorganization is invisible except for improved navigation where archive pages are exposed.
8. As a site visitor, I want Article images, downloads, and linked assets to render and download correctly, so that Article content remains complete.
9. As a site visitor, I want Article RSS output to continue including the same Articles, so that feed readers do not lose archive content.
10. As a site visitor, I want category, tag, and Author pages to continue include the same Articles, so that filtering and Author Profiles remain accurate.
11. As an Author, I want my authors: byline to remain unchanged during migration, so that my stable Author taxonomy key and Profile association remain intact.
12. As an Author, I want to add images or downloads beside a new Article, so that related resources are versioned and reviewed with the Article.
13. As an Author, I want a clear source convention for new Articles, so that I can place a submission in the correct year and month without guessing.
14. As a maintainer, I want each Article's source to be grouped with its resources, so that updating an Article does not require a separate static-asset search.
15. As a maintainer, I want the original dated Article slug retained as a route contract, so that migration work cannot unintentionally alter public URLs.
16. As a maintainer, I want year and month archives to be explicit branch bundles, so that their metadata, content, and templates are independently controllable.
17. As a maintainer, I want Articles to remain regular pages, so that the existing Article template and its page-level behavior continue to apply.
18. As a maintainer, I want the all-Articles listing to traverse nested branches, so that moving Articles under year and month directories does not omit them.
19. As a maintainer, I want a pilot migration and route comparison before bulk movement, so that route, media, taxonomy, and feed regressions are caught early.
20. As a maintainer, I want migration batches to remove the flat source once its bundle is authoritative, so that duplicate content cannot be published.
21. As a maintainer, I want existing static Article media to remain published at its current URL until explicitly migrated, so that media relocation is not coupled to structural migration.
22. As a maintainer, I want Article-local media migration to be possible later, so that the organization can adopt page resources incrementally without another hierarchy redesign.
23. As a search-engine visitor, I want canonical Article routes and structured Article metadata to remain stable, so that the archive does not lose indexing continuity.
24. As a release reviewer, I want an automated generated-site contract check, so that every migration batch proves the published behavior rather than merely validating source files.

Implementation Decisions

• The Article archive becomes a hierarchy of year and month branch bundles. A year branch contains month branches; those branches are intentional public archive pages.
• Each Article becomes a leaf bundle beneath its publication year and two-digit month. Its content entry point remains a regular page, preserving the site's existing Article page template selection and page-level features.
• Article source directory names use the non-date portion of the existing Article slug to avoid repeating publication date already encoded by the year/month hierarchy. Each Article declares its current full dated route using front matter url, which is the immutable public-route compatibility contract.
• All existing Article front matter is preserved, including title, description, publication date, categories, tags, aliases, and authors:. The author name remains the stable Author taxonomy key; no Profile or byline migration is part of this work.
• Root archive pagination changes from an immediate-child collection to a recursive regular-page collection. Year and month archive lists use the page collection appropriate to their hierarchy so they display Articles rather than branch metadata.
• Archive templates distinguish the root Article archive from year and month archive pages only where their headings, descriptions, or navigation need to differ. Article pages continue using the current regular-page presentation; no per-Article section template is introduced.
• Existing root-relative Article media in the static asset tree remains in place and existing content references remain untouched in the hierarchy migration. A later, separately scoped change may place individual assets in their owning leaf bundle and update links or templates to resolve them as page resources.
• The Article contribution workflow and content archetype are updated to create the year/month/Article leaf-bundle structure, collect the required full URL override, and preserve existing front matter expectations.
• Migration begins with a representative pilot that includes an Article with aliases and static media. After the generated-site contract passes, the remainder migrates in reviewable batches. Each moved Article has one authoritative source; flat copies are removed.
• No global permalink rule is introduced for this migration. Per-Article full URL overrides make route preservation explicit and allow each existing dated slug to remain stable despite the new source hierarchy.

Testing Decisions

• The primary and highest test seam is a production Hugo build followed by a generated-site contract check. It tests the public site behavior: emitted Article pages, root pagination membership, year/month archives, canonical URLs, aliases, linked media, RSS membership, and Author/category/tag visibility. It must not assert source-directory internals beyond the behavior those internals enable.
• Establish a pre-migration inventory of canonical Article routes, aliases, Article metadata, and referenced static media. The contract check compares generated output to that inventory for every migrated batch.
• The pilot must cover an Article with an Author Profile association, taxonomy metadata, aliases, and Article media. It demonstrates that the existing Article page template, SEO metadata, structured data, and root archive behavior continue to work for leaf-bundle content.
• Existing project verification already performs a production Hugo build in continuous integration and validates a generated output feed. Extend this generated-output approach rather than introducing source-text or unit tests for template implementation details.
• Run the existing production build path after each migration batch. The route contract check is additive and should fail on a missing canonical page, missing alias redirect, missing asset, changed all-Articles membership, or lost archive/feed/taxonomy discoverability.

Out of Scope

• Changing Article editorial content, titles, dates, categories, tags, aliases, or Authors.
• Changing published Article routes, aside from retaining the existing routes through explicit compatibility configuration.
• Moving existing static Article media into page resources as part of the structural migration.
• Redesigning Article, Author Profile, taxonomy, RSS, schema, or search user interfaces.
• Reorganizing non-Article content such as podcast episodes, community resources, calendar events, or Modules.
• Adding redirects for deliberately unchanged canonical routes.

Further Notes

Hugo treats directories containing _index.md as branch bundles and directories containing index.md as leaf bundles. This design uses branch bundles where hierarchy and archive pages are needed, and leaf bundles where a regular Article page needs resource ownership. The source layout therefore becomes Article archive → year → month → Article while each Article's established dated slug remains its canonical public route.

The migration-research record contains the official Hugo source links for bundle types, nested sections, recursive page collections, page resources, URLs, and aliases.