mirror of
https://github.com/kennethreitz/kennethreitz.org.git
synced 2026-06-05 22:50:17 +00:00
kennethreitz
2ee4b57d77
- Reduced dependencies from 13 to 5 packages (66% reduction) - Removed unused packages: pydantic, fastapi, uvicorn, pygments, boto3, pillow, background, markdown - Kept essential packages: flask, gunicorn, gevent, mistune, pyyaml - Moved docs/ from data/docs/ to root directory for better organization - Updated all internal documentation links to reflect new location 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
188 lines
6.3 KiB
Markdown
188 lines
6.3 KiB
Markdown
# 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](https://github.com/kennethreitz/kennethreitz.org)**
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```markdown
|
|
# My Essay
|
|
|
|
*January 2025*
|
|
|
|
Content here with automatic title and date extraction...
|
|
```
|
|
|
|
### Sidenotes
|
|
|
|
Add Tufte-style sidenotes for non-disruptive annotations:
|
|
|
|
```html
|
|
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](/docs/getting-started)** - Set up your first TufteCMS site from scratch
|
|
- **[Content Structure](/docs/content-structure)** - Learn how to organize your markdown files effectively
|
|
|
|
### Content Creation
|
|
- **[Sidenotes Guide](/docs/sidenotes)** - Master Tufte-style marginal annotations
|
|
- **[Content Structure](/docs/content-structure)** - File naming, URL patterns, and organization strategies
|
|
|
|
### Customization & Deployment
|
|
- **[Customization](/docs/customization)** - Templates, styling, and brand integration
|
|
- **[Deployment](/docs/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](/docs/deployment) for platform-specific instructions.
|
|
|
|
### Cross-References
|
|
Throughout these guides, you'll find extensive cross-linking between concepts. For example:
|
|
- [Sidenotes](/docs/sidenotes) integrate with the [content structure](/docs/content-structure) for optimal placement
|
|
- [Customization](/docs/customization) builds on concepts from [getting started](/docs/getting-started)
|
|
- [Deployment](/docs/deployment) assumes familiarity with [content organization](/docs/content-structure)
|
|
|
|
---
|
|
|
|
*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.* |