kennethreitz.org/docs/index.md

TufteCMS Documentation

An experimental Flask-based content management system for markdown-driven websites

TufteCMS is an experimental, minimal, opinionated framework for building content-rich websites from markdown files. It emphasizes readability, cross-referencing, and contemplative design patterns inspired by Edward Tufte's principles of information design.

Experimental Software: TufteCMS is in active development and should be considered experimental. APIs may change, features may be incomplete, and documentation may lag behind implementation. Use in production at your own discretion.

Core Philosophy

• Markdown-first: All content lives in readable markdown files
• Human-readable URLs: Clean, semantic paths that mirror content structure
• Cross-referencing: Rich internal linking and connection tracking
• Tufte-style annotations: Marginal sidenotes for depth without disruption
• Caching-aware: Intelligent content caching with background warming
• Minimal dependencies: Flask + essential markdown processing

Download & Installation

GitHub Repository

Download TufteCMS from the official repository:

Download TufteCMS

# Clone the repository
git clone https://github.com/kennethreitz/kennethreitz.org.git
cd kennethreitz.org

# The TufteCMS framework is in the tuftecms/ directory
# Your content goes in the data/ directory

Installation Options

Option 1: Use as Framework Template

# Copy the tuftecms/ directory to your new project
cp -r tuftecms/ /path/to/your/new-site/
cp engine.py /path/to/your/new-site/

# Install dependencies
cd /path/to/your/new-site/
uv sync  # or pip install flask markdown

Option 2: Fork and Customize

# Fork the repository on GitHub, then:
git clone https://github.com/yourusername/kennethreitz.org.git
cd kennethreitz.org

# Remove existing content and add your own
rm -rf data/essays/*
# Add your content to data/

Quick Start

# engine.py
from tuftecms import create_app

app = create_app()
app.run(debug=True)

Your content structure:

data/
├── index.md              # Homepage content
├── essays/               # Blog posts and essays
│   ├── 2025-01-01-hello-world.md
│   └── index.md          # Essays index
├── docs/                 # Documentation
│   └── index.md          # This file
└── static/              # Static assets
    ├── images/
    └── css/

Key Features

Automatic Content Discovery

TufteCMS automatically serves markdown files based on URL structure:

• / → data/index.md
• /essays/hello-world → data/essays/hello-world.md
• /docs → docs/index.md
• /docs/getting-started → docs/getting-started.md

Intelligent Content Analysis

TufteCMS automatically extracts metadata from your content structure:

# My Essay

*January 2025*

Content here with automatic title and date extraction...

Sidenotes

Add Tufte-style sidenotes for non-disruptive annotations:

This is the main text.
<label for="sn-1" class="margin-toggle sidenote-number"></label>
<input type="checkbox" id="sn-1" class="margin-toggle"/>
<span class="sidenote">This is a sidenote that appears in the margin.</span>

Cross-Reference Tracking

TufteCMS automatically tracks internal links and builds:

• Connections index: What links to what
• Backlinks: Incoming references to each page
• Graph visualization: Interactive network of content relationships

Content Indexes

The system automatically generates:

• Sidenotes index: All marginal annotations across the site
• Outlines index: Heading structure from all articles
• Quotes index: Blockquotes extracted from content
• Terms index: Key concepts with cross-references
• Archive: Chronological content organization

Directory Structure

kennethreitz.org/
├── data/                 # All content
│   ├── index.md         # Homepage
│   ├── essays/          # Blog posts
│   ├── docs/            # Documentation
│   └── static/          # Images, assets
├── tuftecms/            # Framework code
│   ├── app.py          # Flask application factory
│   ├── blueprints/     # Route handlers
│   ├── core/           # Markdown rendering, caching
│   ├── utils/          # Content utilities
│   ├── templates/      # Jinja2 templates
│   └── static/         # CSS, JavaScript
└── engine.py           # Development server

Documentation Guide

Getting Started

• Getting Started - Set up your first TufteCMS site from scratch
• Content Structure - Learn how to organize your markdown files effectively

Content Creation

• Sidenotes Guide - Master Tufte-style marginal annotations
• Content Structure - File naming, URL patterns, and organization strategies

Customization & Deployment

• Customization - Templates, styling, and brand integration
• Deployment - Production configuration and hosting options

Deployment Ready

TufteCMS is designed for easy deployment across platforms:

• Traditional servers - Nginx + Gunicorn configuration examples
• Platform-as-a-Service - Heroku, Railway, Fly.io ready
• Static generation - Build HTML for Netlify, Vercel, GitHub Pages
• Containerization - Docker examples for scalable deployment

See the complete deployment guide for platform-specific instructions.

Cross-References

Throughout these guides, you'll find extensive cross-linking between concepts. For example:

• Sidenotes integrate with the content structure for optimal placement
• Customization builds on concepts from getting started
• Deployment assumes familiarity with content organization

---

TufteCMS embodies the principle that technology should serve human consciousness, not exploit it. Every design choice prioritizes readability, contemplation, and authentic expression over engagement metrics or algorithmic optimization.