Last updated on June 8, 2026
Following completion of the Portal Rendering System Refactor, attention shifted toward a growing architectural issue within the development site itself.
Over time, the site had accumulated several overlapping content structures: Pages used for site systems and documentation, Posts used for active development tasks, Chapters used for tutorials, guides, completed work, and long‑form documentation, and Updates maintained as content inside a single running update page.
While functional, the structure reflected the site’s historical evolution rather than its current purpose. As the amount of documentation increased, the distinction between content types became increasingly unclear. The objective of this refactor was to establish a clean and durable content architecture before additional development work continued.
Legacy structure
The previous site organization relied primarily on:
- Pages – engine systems and navigation (VPS configuration, security documentation, site tools, search utilities).
- Posts – active development tasks.
- Chapters – multiple unrelated purposes: Demystifying Code tutorials, Guides & Unrelated documentation, completed tasks, historical development notes.
- Update Page – a single page containing manually appended development updates spanning more than a year of work.
Although this structure functioned adequately during early development, it mixed fundamentally different content types together and made future expansion increasingly difficult.
New content architecture
The site was reorganized around four primary content types.
Page
Pages remain reserved for permanent site systems and operational documentation (VPS infrastructure, Linux administration, security systems, search tools, navigation hubs). Pages now represent the site’s operational engine.
Article CPT
A new Article CPT replaces the former Chapter‑based documentation model. Articles are intended for tutorials, guides, technical documentation, and long‑form educational content. Rather than using separate post types for different article categories, organization is handled through a dedicated Series taxonomy. Examples: Demystifying Code, Guides & Unrelated. This allows future documentation series to be added without creating additional post types.
register_post_type('article', [
'public' => true,
'show_in_rest' => true,
'supports' => ['title', 'editor', 'excerpt', 'thumbnail']
]);Update CPT
Site updates were extracted from the long‑running update page and converted into individual update entries. Each update now exists as a standalone content object with title, excerpt, full update body, and original publication date. This provides proper chronological archives, native sorting, dedicated update templates, individual URLs, and future filtering capabilities.
register_post_type('update', [
'public' => true,
'show_in_rest' => true,
'supports' => ['title', 'editor', 'excerpt']
]);Task CPT
Development work is now represented through a dedicated Task CPT, replacing the previous dependency on standard WordPress Posts. Tasks are organized through a dedicated Status taxonomy (Active, Completed).
register_taxonomy('status', ['task'], [
'hierarchical' => true,
'show_in_rest' => true
]);This establishes a formal distinction between active work and historical accomplishments.
Project taxonomy
As the number of tasks increased, a second organizational layer became necessary: a dedicated Project taxonomy. Examples: Portal System, Element System, Attribution Framework, Search & Discovery, Infrastructure, Music Platform, Content Architecture. This allows large collections of related tasks to be grouped together while preserving task‑level granularity. Example URL structure: post_type=task&project=portal-system. Tasks now exist within both Status (Active/Completed) and Project (functional area of work), providing significantly better organization than the original flat task list.
Series taxonomy refactor
The former Chapter classification system was replaced with a dedicated Series taxonomy attached to Articles.
register_taxonomy('series', ['article'], [
'hierarchical' => true,
'show_in_rest' => true
]);Current series include Demystifying Code and Guides & Unrelated. This allows documentation to scale naturally without requiring additional post types.
Navigation refactor
The sidebar navigation was redesigned to align with the new architecture. The previous implementation mixed multiple content models together. Navigation now consists of independent shortcode‑driven sections:
- Site Resources – Site Updates, Active & Completed Tasks, Site Tools, GitHub, Main Site.
- The Engine – Operational and infrastructure documentation.
- Demystifying Code – Article series navigation.
- Guides & Unrelated – Article series navigation.
Each section now functions independently, eliminating the need for large combined navigation queries. Example shortcode registration: add_shortcode('demystifying_nav', 'generate_demystifying_nav');
Homepage refactor
The homepage was restructured to reflect the new content model. Rather than combining unrelated content into a single stream, the homepage now presents clearly separated sections: Site Resources, The Engine, Demystifying Code, Guides & Unrelated. The separation better reflects how visitors actually interact with the site and significantly reduces cognitive overhead.
Dedicated templates
New content‑specific templates were introduced.
Updates Template – A dedicated update archive page displays update entries in reverse chronological order:
new WP_Query([
'post_type' => 'update',
'orderby' => 'date',
'order' => 'DESC'
]);Tasks Template – A dedicated task page groups tasks by Project taxonomy and then subdivides by Status. Example structure:
- Portal System → Active Tasks / Completed Tasks
- Element System → Active Tasks / Completed Tasks
This transformed task management from a simple chronological list into a structured project‑oriented workspace.
Outcome
This refactor establishes a significantly cleaner separation between site systems, documentation, development updates, and active work. The development site now reflects its actual purpose as both a working engineering environment and a long‑term knowledge repository. Most importantly, future growth can occur through taxonomies and templates rather than creating additional custom post types. The architecture is now considerably simpler, more scalable, and more aligned with the site’s long‑term direction.