Rebuilding My Site with Narrative CMS

About the author: I'm Charles Sieg, a cloud architect and platform engineer who builds apps, services, and infrastructure for Fortune 1000 clients through Vantalect. If your organization is rethinking its software strategy in the age of AI-assisted engineering, let's talk.

Twenty years ago, I built a blogging platform called Narrative. It was an ASP.NET-based CMS with advanced features like automatic page rebuilding, a sophisticated tagging system, and comment spam prevention. I used it to power this site from 2003 until 2008, when I abandoned it in favor of WordPress, saying "I am much more interested in blogging than the building of blogging software."

That code sat shelved for nearly two decades. Then, in 2024, I discovered Claude Code and realized that with AI assistance, I could finally bring Narrative back to life as exactly the system I'd always envisioned. This post tells that story.

---

The Original Narrative (2003-2008)

The first iteration of Narrative grew out of necessity. In the early 2000s, ASP.NET lacked a good blogging platform. So I built one.

By June 2005, Narrative had some sophisticated features:

• Smart Rebuilding: Instead of dynamically generating pages on every request, Narrative automatically rebuilt pages only when content or templates changed
• Tagging Assemblies: A plugin system where code libraries could recognize template tags and replace them with dynamic content, bypassing ASP.NET entirely
• Comment Spam Prevention: A custom CAPTCHA system to combat the thousands of spam comments hitting the site
• XHTML Compliance: Proper DOCTYPE handling for search engine indexing

I was proud of what I'd built. But by 2008, I'd moved from Windows to Mac, from .NET to LAMP stacks, and WordPress had matured into an excellent platform. Maintaining my own CMS no longer made sense. I walked away.

The Long Hibernation

For seventeen years, the Narrative codebase gathered digital dust. Occasionally, I'd think about it: the clean architecture, the template system, the satisfaction of building something that worked exactly as I wanted. But the prospect of rebuilding it from scratch seemed daunting.

I tried Jekyll. I tried Hugo. I tried Gatsby and Next.js and a dozen other static site generators. Each had strengths, but I kept running into the same friction points:

• Limited Markdown control: I wanted fine-grained control over parsing and rendering
• Template limitations: Most systems only gave you rendered HTML, not structured content
• Deployment complexity: I wanted built-in AWS S3 and CloudFront integration
• Performance bottlenecks: Large sites needed intelligent caching and incremental builds

I knew what I wanted. I just didn't have the time or energy to build it.

Enter Claude Code

In late 2024, I started experimenting with Claude Code for software development projects. It changed how I approach building software.

AI-assisted development centers on iteration, refinement, and conversation. You explain what you want, see an implementation, test it, find the edge cases, and iterate until it works.

With Claude Code, I could finally resurrect Narrative as a modern Python static site generator with all the features I'd dreamed about.

Building with AI: The Development Process

The development of the new Narrative was unlike any project I'd worked on before.

Iterative Architecture Design

I started by describing the core architecture I wanted:

"I need a Markdown parser that maintains document structure: preserving the hierarchy of headings, associating paragraphs with their parent sections, and extracting metadata like images and links, beyond simple HTML conversion."

Claude Code generated an initial implementation. We tested it. Found edge cases with nested lists. Refined it. Added support for blockquotes. Handled inline formatting. Each iteration built on the last, with me providing domain knowledge and Claude providing implementation expertise.

The result is a parser that goes far beyond simple Markdown-to-HTML conversion. It builds a complete document object model that templates can interrogate and manipulate.

Feature Development Through Conversation

Every feature in Narrative came through this iterative dialogue:

Me: "The breadcrumb navigation should show 'Blog' for recent posts but 'Archive' for posts older than one year. And it should hide the year directory in breadcrumbs for recent posts to reduce clutter."

Claude: Generates breadcrumb logic with date calculations and Jinja2 template code

Me: "It's not working. The year still shows for recent posts."

Claude: Analyzes the template, identifies that Jinja2's variable scoping was the issue, implements a namespace-based solution

This kind of back-and-forth debugging happened dozens of times. Claude Code could spot issues I missed, suggest alternative approaches, and implement solutions faster than I could type them.

Solving Problems I Couldn't Solve Alone

Some features required expertise I didn't have. SCSS compilation, for example. I knew I wanted to compile SCSS to CSS during builds, but I'd never worked with libsass in Python.

I described what I needed. Claude Code showed me how to:

• Set up include paths for @import statements
• Handle compilation errors gracefully
• Ensure the CSS output directory existed before writing
• Integrate it into the build process

Within an hour, I had working SCSS compilation. That same task would have taken me days of documentation reading and trial-and-error.

The AI as Pair Programmer

The best analogy I have is pair programming, but with a partner who:

• Never gets tired
• Has instant recall of Python standard library functions
• Can generate regex patterns on demand
• Writes comprehensive docstrings
• Follows PEP 8 style guidelines automatically
• Can refactor code while maintaining functionality

When I needed to add CloudFront invalidation after S3 uploads, I just described the workflow. Claude Code generated boto3 client setup, error handling, logging, and the full integration, all following the existing code patterns.

What I Contributed

My role remained critical:

• Domain expertise: What features a static site generator needs
• Architecture decisions: When to use caching, how to structure pages
• Testing: Trying edge cases, finding bugs, verifying behavior
• Direction: Knowing when to iterate vs. when to move on
• Integration: Ensuring components worked together coherently

I wrote requirements. Claude Code wrote implementations. I tested. We refined. It was collaborative in a way I'd never experienced before.

Why This Succeeded Where the Original Failed

The original Narrative died because maintaining it became a burden. This version thrives because:

1. AI handles the tedious parts: Boilerplate, error handling, edge cases
2. Documentation comes naturally: Claude Code writes docstrings as it codes
3. Iteration is cheap: Want to refactor? Describe the change, review the diff, done
4. Best practices emerge: The AI suggests patterns I hadn't considered
5. I focus on features, not implementation: I think about what I want; Claude handles how

And it's fun again. Every session feels productive. Every feature request becomes reality within minutes or hours, not days or weeks.

The Result: A Modern Narrative

Narrative is built around a clean, modular architecture with several key components:

Markdown Processing

The core Markdown parser goes well beyond simple HTML conversion. The parser:

• Maintains a hierarchical document structure with headings and associated paragraphs
• Supports advanced features like nested lists, blockquotes, and code blocks
• Extracts metadata like images, alt text, and titles
• Provides structured access to content for templates
• Uses pre-compiled regex patterns for optimal performance

Template System

The template system uses Jinja2, and templates have access to the full document structure, including the raw content hierarchy. This means you can:

• Generate table of contents from heading hierarchies
• Access individual paragraphs and apply custom styling
• Process images with metadata-aware rendering
• Create sophisticated layouts based on content structure

Intelligent Caching

Narrative includes a Redis-backed caching system that:

• Tracks dependencies between pages (like posts and tag indexes)
• Enables incremental builds that only regenerate changed content
• Monitors template modifications and rebuilds affected pages
• Maintains page hashes to detect content changes

Features That Matter

Intelligent Rebuilding

Like the original Narrative from 2003, the modern version knows exactly what needs to be regenerated when something changes. The current implementation goes much further.

The system tracks dependencies between pages. When a blog post is updated, it rebuilds that post along with the blog index, relevant tag pages, and RSS feeds. When you modify a template, it rebuilds only the pages that use that template. And when SCSS files change, it performs a CSS-only rebuild without touching any HTML pages.

Redis caching with page hashes backs this dependency tracking. The system maintains checksums of every page and template, detecting changes at a granular level. During development, this means instant feedback; save a file and see changes immediately. For production deployments, it means fast builds that only regenerate what has actually changed.

The breadcrumb navigation demonstrates this intelligence too. It shows "Blog" for recent posts and "Archive" for older ones, and hides year directories in breadcrumbs for recent posts to reduce clutter. This kind of context-aware behavior permeates the entire system.

SCSS Compilation

Narrative automatically compiles SCSS to CSS during the build process, with support for:

• @import statements for modular stylesheets
• Compressed output for production
• Source path resolution for clean organization
• Error handling with helpful debugging information

I can organize my styles into \_colors.scss, _typography.scss, and other partials, then import them into a main style.scss file. It all just works.

Powerful Shortcode System

Narrative includes a flexible shortcode system that extends Markdown with dynamic functionality. Shortcodes are processed before the Markdown parser runs, allowing them to generate HTML that integrates directly with your content.

The system comes with several built-in shortcodes that I use throughout this site:

• article_link: Creates links to other posts or articles by name, automatically resolving the correct path. This post uses it to reference older Narrative posts without hardcoding URLs.
• toc: Generates a table of contents from the document's heading hierarchy, with customizable depth and styling.
• youtube: Embeds YouTube videos with proper responsive containers.

Creating custom shortcodes is straightforward. Each shortcode is a Python plugin that receives the shortcode context and returns HTML. The architecture is similar to the original Narrative's "Tagging Assemblies" concept from 2003, modernized with a clean plugin interface.

Shortcodes also have access to the full site context, including all pages, configuration values, and the current page's metadata. This enables cross-referencing and dynamic content generation that static Markdown alone cannot support.

CloudFront Integration

Built-in S3 upload and CloudFront integration streamline deployment. When I deploy to staging or production, Narrative:

1. Uploads all files to the configured S3 bucket
2. Sets appropriate MIME types for HTML, CSS, JavaScript, images, and other assets
3. Automatically creates a CloudFront invalidation to clear the cache
4. Logs the invalidation ID and status for verification

The entire process takes seconds, and visitors see the latest content immediately.

HTML and JavaScript Minification

Modern websites benefit from minification: removing unnecessary whitespace, comments, and formatting from HTML and JavaScript to reduce file sizes and improve load times. Most minification tools, however, require heavyweight dependencies and can break code if misconfigured.

Narrative includes a custom-built minifier that's lightweight, dependency-free, and designed specifically for the HTML it generates. The minifier:

• Removes all HTML comments while preserving the actual content
• Compresses whitespace between tags without breaking layout
• Minifies JavaScript inline within <script> tags:
• Removes single-line (//) and multi-line (/* */) comments
• Eliminates unnecessary whitespace and line breaks
• Preserves string literals, regex patterns, and template strings
• Compresses operators and punctuation
• Protects critical content by preserving whitespace in <pre>, <textarea>, and <style> tags
• Fails gracefully by returning the original HTML if minification encounters an error

The dual deployment approach adds further value. By default, minification happens at deployment time when uploading to S3. You develop and debug with readable, formatted HTML, then automatically optimize for production. You can also test minified builds locally using the --minify flag, ensuring everything works correctly before deployment.

I built the minifier collaboratively with Claude Code, and it handles edge cases that would have taken weeks to debug manually: distinguishing between // in comments versus // in URL strings, or preserving JavaScript regex literals while removing comment blocks. This kind of seemingly-simple-but-actually-complex feature is where AI-assisted development delivers the most value.

Tag and Topic Organization

The system includes sophisticated content organization:

• Tags for blog posts with automatic tag index generation
• Topics for longer-form articles organized by subject
• Tag and topic pages with proper pagination
• Automatic generation of index pages

Real-Time Development

During development, Narrative watches the source directory and automatically:

• Performs full rebuilds when content or templates change
• Does CSS-only rebuilds when SCSS files are modified
• Injects auto-reload scripts so the browser refreshes automatically
• Adds cache-control headers to prevent stale content

The feedback loop is instant. I save a file and see changes immediately.

Technical Implementation

The technical stack breaks down as follows:

Language and Stack

• Python 3.9+ for the core engine
• Jinja2 for templating
• PyYAML for frontmatter parsing
• libsass for SCSS compilation
• Boto3 for AWS integration
• Redis for caching (via Valkey)

Docker-Based Development

The entire system runs in Docker containers:

• Backend CMS in Python
• Valkey (Redis-compatible) for caching
• Optional React frontend for build management
• All orchestrated with Docker Compose

WebSocket Integration

The backend includes a Flask-SocketIO server that provides real-time communication:

• Build status updates
• File change notifications
• SCSS rebuild events
• Deployment progress

This powers the optional React frontend, but the system also works with just API calls or command-line usage.

Performance

One of my key goals was performance, both in build times and runtime:

• Fast builds: The engine builds the hierarchical document structure once per page, then caches it
• Incremental rebuilds: The system regenerates only changed content
• Pre-compiled patterns: The engine compiles all regex patterns once at startup
• Efficient templates: Jinja2's template caching ensures fast rendering

On this site with 50+ posts and articles, a full build takes under 2 seconds. Incremental builds complete in milliseconds.

What's Next

Building with AI assistance means adding features no longer feels daunting. I'm continually refining Narrative, and some items on the roadmap:

• Image optimization and responsive image generation
• Built-in search functionality
• RSS/Atom feed enhancements
• Multi-language support
• Additional built-in shortcodes

Each of these would have taken weeks in the old development model. With Claude Code, they're weekend projects.

The Future of Development

This experience has fundamentally changed how I think about software development. The transformation is in the collaboration model. I can focus on:

• Understanding what users need
• Designing effective solutions
• Testing edge cases
• Ensuring quality

While Claude Code focuses on:

• Implementation details
• Best practices
• Error handling
• Documentation
• Code consistency

Together, we're far more productive than either could be alone.

Open Source?

Currently, Narrative is a private project powering my personal site and a few client sites. I'm considering open-sourcing it once the documentation is more complete and the API is more stable.

If I do open source it, the development workflow would be unique. Contributors could describe features, iterate with AI assistance, and submit well-tested, documented code. The barrier to contribution drops dramatically.

A Personal Reflection

Twenty years ago, I built Narrative because I had to. I needed a blogging platform and none existed for my stack.

Today, I rebuilt Narrative because I could. Because AI assistance made it feasible to create exactly what I wanted without sacrificing months of my life to do it.

I abandoned the original Narrative because maintaining it required more effort than it returned. This version is sustainable because the effort-to-value ratio has fundamentally changed. When you can add a feature in an afternoon instead of a week, when debugging is a conversation instead of hours of print statements, when refactoring is describing what you want instead of manually updating hundreds of lines, building custom software makes sense again.

If you're interested in learning more or have questions about AI-assisted development, static site generation, or resurrecting twenty-year-old projects, feel free to reach out via Twitter or LinkedIn.

---

Conclusion

The rebirth of a project I started in 2003 and abandoned in 2008 powers this site. It sat dormant for seventeen years until AI assistance made it both possible and practical to bring it back.

Narrative CMS 2025 is everything the original aspired to be: fast, flexible, and exactly tailored to my needs. More than that, it represents something larger: proof that AI-assisted development amplifies what a single developer can build.

I created every page on this site, every feature, every line of code through iteration between human intent and AI implementation. The code is mine. The architecture is mine. The vision is mine. The speed, the completeness, the polish: those came from collaboration with Claude Code.

This is the present of development.