Skip to content

Project Retrospective: The Ardens Documentation System Overhaul

Modernization of Genealogy and Ardens Documentation Systems

Status: Complete

1. Executive Summary: From Legacy to AI-Ready

This project successfully modernized the underlying architecture of two core documentation sites—Genealogy (ManyRoads) and Ardens—migrating them from an outdated, difficult-to-maintain legacy setup to a fast, secure, and future-proof static documentation system.
The primary goals were:

  1. Enhance Security: Implement modern access controls and eliminate vulnerabilities.
  2. Improve Discoverability: Replace slow, antiquated internal search with a fast, client-side solution and optimize for modern search engine optimization (SEO).
  3. Future-Proof Content: Structure all documents using Markdown and create machine-readable manifest files to ensure content is accessible and understandable by current and future AI models.

2. Technical Challenge: The Legacy System

The previous system, built on older PHP frameworks, presented several critical challenges:

  • Maintenance Overhead: The dependency on a PHP/MySQL stack for basic document serving and search created unnecessary complexity.
  • Security Risk: The system relied on dated access control logic, which was cumbersome to verify and maintain.
  • Indexing Barrier: The lack of structured data meant search engines and emerging AI knowledge bases struggled to fully map and understand the content, particularly the hierarchical relationships and summaries.

3. The Solution: The Ardens Architecture

Our strategy was to implement a static generation approach for indexing, utilizing a single, secure PHP script (generate_index.php) as an authoring tool to process all Markdown source files.

Key Components Developed:

| File Name | Purpose | Technical Benefit |
| generate_index.php | Automation Core | Scans the /content directory, extracts YAML front matter (Title, Tags, Summary), converts Markdown to content fragments, and generates the index files. |
| search_index.json | User Search | A flat, comprehensive index containing the title, content, and path for every document. Powers the lightning-fast, client-side search function (eliminating the need for a database). |
| knowledge_manifest.json | AI/Machine Access | A hierarchical, tree-like JSON structure that maps the relationships between documents and explicitly includes the Summary and Tags. This structure is optimized for consumption by external AI/LLMs. |
| sitemap.xml | Search Engine Optimization | A complete, dynamically generated sitemap essential for guaranteeing all content pages are discovered and indexed by Google and other search engines. |
| .htaccess | Security & Verification | Implemented a robust security protocol to protect the generate_index.php script and secure the site generally, which also allowed for immediate Google Search Console verification. |

4. Results and Project Conclusion

The project concluded with all sites (Genealogy and Ardens) successfully deployed, verified, and running on the new architecture.

  • Over 420 Files (202 for Ardens, 219 for Genealogy) are now managed by this new architecture, representing a massive scope.
  • Security is confirmed with successful .htaccess and Google verification steps.
  • The sites are positioned to capture value from generative AI search by explicitly providing structured data via the knowledge_manifest.json.
  • The system is highly robust: once the index files are created, the temporary generate_index.php can be deleted, leaving a purely secure, static documentation environment.

This foundational work ensures the valuable historical and genealogical resources remain accessible, fast, and competitive in the modern web landscape.