Features
Content Publishing That Builds Itself
A 9-layer architecture covering everything from Markdown processing to AI-powered search, with incremental builds that finish in under two seconds.
Layer 1
Content Engine
Advanced Markdown Processing
Heading hierarchy extraction, image metadata, and CSS class support. Rich structured content from plain Markdown files.
Page Discovery and Frontmatter
Automatic page discovery with YAML frontmatter parsing supporting 19+ date formats. Write content, and Narrative finds it.
Jinja2 Template Rendering
Full access to structured content — headings, paragraphs, images, and metadata — inside your templates. Complete control over output.
Extensible Shortcode System
10 built-in shortcodes: article links, callouts, code tabs, Mermaid diagrams, YouTube/Vimeo embeds, table of contents, and more. Add your own via the plugin architecture.
Plugin Architecture
Custom shortcodes and automations through a clean plugin interface. Extend Narrative without modifying core code.
Tags and Topics
Tag and topic-based content organization with automatic slug generation. Browsable taxonomy pages generated at build time.
Multi-Site Management
Generate multiple sites from a single Narrative installation. Shared templates, shared shortcodes, independent content.
Layer 2
Asset Pipeline
Image Optimization
Automatic JPEG and PNG optimization with configurable quality. Smaller files, faster pages, zero manual effort.
WebP Conversion
Automatic WebP generation with <picture> element output for modern browsers. Every image served in the optimal format.
SCSS Compilation
Full SCSS support with @import resolution. Write modular stylesheets that compile to optimized CSS at build time.
Hash-Based Asset Caching
Content-hash tracking ensures only changed files are reprocessed. Skip work that doesn't need doing.
Layer 3
Build Intelligence
Incremental Builds
Valkey/Redis dependency tracking delivers ~1.5 second rebuilds. Only regenerate what changed, even on large sites.
Collection-Based Change Detection
Edit a post and only affected pages rebuild. Smart dependency graphs know exactly what needs updating.
File Watching
1-second debounce for development mode. Edit, save, see — no manual rebuild or browser refresh needed.
Pagination-Aware Rebuilds
Changes to paginated content trigger rebuilds across all affected pages. No stale pagination links.
Layer 4
Deployment
Multi-Stage AWS Deployment
Deploy to S3 with CloudFront CDN in a single command. Staging and production environments with per-stage configuration.
Incremental Uploads
Hash-based change detection skips unchanged files. Only upload what's new or modified.
Targeted Cache Invalidation
Per-path CloudFront invalidation for small changes, automatic wildcard invalidation for large deploys.
Upload-Time Minification
HTML and JavaScript minification at deploy time with per-stage configuration. Smaller payloads, faster loads.
VelvetRope™ Access Control
Client-side key gate for staging and stealth sites. Visitors provide a key via URL parameter or lock screen. Works with any static host — S3, CloudFront, Netlify.
Layer 5
Infrastructure Provisioning
Full AWS Provisioning
Complete infrastructure provisioning via boto3. From zero to production-ready with a single command.
S3, ACM, CloudFront, Route 53
S3 buckets, ACM SSL certificates, CloudFront distributions, and Route 53 DNS records. Everything you need to serve a site.
ECR and Lambda Deployment
Container registry and Lambda function deployment for serverless features like semantic search.
Dry-Run Preview
Preview every infrastructure change before it happens. No surprises, no accidental resource creation.
Layer 6
Content Quality
AI Content Detection
Sapling API integration with configurable thresholds. Per-file scoring written to frontmatter — files already checked are skipped.
Link Checker
Broken link detection for internal and external URLs. Crawls rendered HTML after build to catch dead links before they reach production.
Custom Minifier
Zero-dependency HTML and JavaScript minification. No external tools, no bloated node_modules. Just smaller output.
Layer 7
Semantic Search
Vector Embeddings
Lambda-based semantic search with vector embeddings. Search by meaning, not just keywords.
Document Chunking
Automatic content segmentation into embedding-sized chunks for accurate similarity matching.
Similarity Search
Vector index queries return the most semantically relevant content. Fast, accurate, and serverless.
Rate-Limited API
Production-ready search endpoint with built-in rate limiting. Deploy and forget.
Layer 8
Export
React Component Export
Export articles as JSON for integration with React SPAs. Static content, dynamic delivery.
RSS and Atom Feeds
Automatic RSS and Atom feed generation. Subscribers get updates the moment you publish.
XML Sitemap
Automatic sitemap generation for search engine crawlers. Every page indexed, every time.
Layer 9
Integration
MCP Server
8 tools for AI integration: list sites, build, deploy, provision, AI detection, read/write content. Plus MCP resources for site config and build instructions.
Flask REST API
Full content management API. Authentication, real-time WebSocket updates, and programmatic access to everything.
CLI
15+ flags for build, deploy, provision, detect, and export. Everything Narrative can do, accessible from the command line.
How It Works
From Markdown to Production
Write
Author content in Markdown with YAML frontmatter. Use shortcodes for rich embeds, diagrams, and interactive elements.
Build
Static processes Markdown, optimizes images to WebP, compiles SCSS, renders Jinja2 templates, and minifies output.
Iterate
Incremental builds detect changes via Valkey dependency tracking and rebuild only what's needed. Live reload keeps your browser in sync.
Deploy
Push to S3 and CloudFront with a single command. Automatic cache invalidation ensures visitors see the latest content immediately.
Technical Specifications
Under the Hood
Core
- Python 3.9+
- Flask web framework
- Jinja2 template engine
- SQLAlchemy ORM
- PostgreSQL database
- Valkey / Redis caching
Frontend
- React 19 admin interface
- Real-time WebSocket updates
- SCSS compilation
- Pygments syntax highlighting
- Mermaid SVG rendering
Infrastructure
- AWS S3 static hosting
- CloudFront CDN
- ACM certificate provisioning
- Route 53 DNS
- Lambda serverless search
- ECR container registry
Quality
- Docker Compose dev environment
- MCP server integration
- Multi-site generation
Development
100% Built by Claude
Narrative was built entirely by Claude (Anthropic) working alongside a single human supervisor. Every line of code, every test, every deployment: AI-authored with human direction.