kennethreitz.org/docs/getting-started.md

Getting Started with TufteCMS

Build your first content-driven website

TufteCMS transforms markdown files into a rich, interconnected digital garden. This guide walks through setting up your first site.

Note

: TufteCMS is experimental software. Features and APIs may change as the framework evolves.

Installation

TufteCMS requires Python 3.8+ and uses Flask as its web framework.

# Clone or download TufteCMS
git clone https://github.com/user/tuftecms.git
cd tuftecms

# Install dependencies (using uv recommended)
uv sync

# Or with pip
pip install flask mistune

Project Structure

Create your content directory structure:

your-site/
├── data/                 # All your content
│   ├── index.md         # Homepage
│   ├── essays/          # Blog posts
│   │   ├── index.md     # Essays landing page
│   │   └── 2025-01-01-first-post.md
│   └── docs/            # Documentation
├── tuftecms/            # Framework (if not installed as package)
└── engine.py           # Development server

Homepage Template

TufteCMS uses a template-based homepage. Copy the starter template:

# Copy the starter homepage template
cp tuftecms/templates/homepage-starter.html tuftecms/templates/homepage.html

Then customize tuftecms/templates/homepage.html to reflect your unique voice and vision. The starter template provides:

• Basic layout structure
• Sample content sections
• Integration with TufteCMS index counts
• Responsive design elements
• Example of pathway boxes for content organization

Your First Content

Create content pages in the data/ directory:

# data/essays/welcome.md

# Welcome to My Digital Garden

This is my first essay. TufteCMS will automatically serve this at `/essays/welcome`.

I can link to [other pages](/docs) and they'll be tracked in the connections system.

## About This Site

Built with [TufteCMS](/docs) - a framework for contemplative digital publishing.

Development Server

Start the development server:

# Using uv (recommended)
uv run python engine.py

# Or directly with Python
python engine.py

Visit http://localhost:5000 to see your site.

Writing Content

Basic Markdown

TufteCMS supports standard markdown with enhancements:

# Main Heading

## Section Heading

Regular paragraph with *emphasis* and **strong** text.

- Bullet points
- Are supported
- Naturally

1. As are
2. Numbered lists

> Blockquotes are tracked in the quotes index

Code blocks work as expected:
```python
def hello_world():
    return "Hello from TufteCMS!"

Content Structure

TufteCMS automatically extracts metadata from your content:

# Your Content Title

*January 2025*

This becomes the page title automatically. TufteCMS extracts titles from H1 headings and dates from italic date patterns or filenames.

What gets extracted automatically:

• H1 headings (# Title) become page titles
• Italic date patterns (*January 2025*) become publication dates
• Filename dates (2025-01-15-post.md) are recognized for chronological sorting
• Word count and reading time calculated automatically

Internal Linking

Link between pages using clean URLs:

Check out my [latest essay](/essays/programming-philosophy).

See the [complete documentation](/docs) for more details.

TufteCMS automatically:

• Tracks these connections
• Builds backlink indexes
• Creates network visualizations
• Generates related content suggestions

Adding Sidenotes

Sidenotes provide non-disruptive way to add depth:

This is the main narrative flow.<label for="sn-example" class="margin-toggle sidenote-number"></label><input type="checkbox" id="sn-example" class="margin-toggle"/><span class="sidenote">This appears in the margin without disrupting the reading flow.</span> The text continues naturally.

Critical formatting notes:

• Sidenotes must be inline with no line breaks
• Place them at the end of sentences (after the period)
• Keep them away from code blocks
• Use descriptive IDs like sn-technique-name

Directory Organization

Organize content logically:

data/
├── index.md              # Homepage
├── essays/               # Long-form writing
│   ├── index.md         # Essays index page
│   ├── 2025-01-01-introduction.md
│   └── 2025-01-15-philosophy.md
├── notes/               # Shorter observations
│   ├── index.md
│   └── daily-thoughts.md
├── projects/            # Work portfolio
│   ├── index.md
│   └── tuftecms.md
└── docs/               # Documentation
    ├── index.md
    └── getting-started.md

URLs automatically follow this structure:

• /essays/introduction → data/essays/introduction.md
• /projects/tuftecms → data/projects/tuftecms.md
• /notes → data/notes/index.md

Content Discovery Features

TufteCMS automatically provides:

Indexes

• Archive: Chronological listing of all content
• Connections: Cross-reference mapping between pages
• Sidenotes: All marginal annotations across the site
• Quotes: Blockquotes extracted from content
• Terms: Key concepts with occurrence tracking

Navigation

• Search: Full-text search across all content
• Graph: Interactive visualization of content connections
• Random: Serendipitous content discovery
• Related: Algorithm-suggested related content

Next Steps

Now that you have a basic site running:

1. Organize your content - Learn about content structure for optimal file organization
2. Add depth with sidenotes - Master Tufte-style annotations for contemplative writing
3. Customize your site - Explore customization options for templates and styling
4. Deploy to production - Follow the deployment guide for hosting options

Related Documentation

• Content Structure - Essential reading for organizing larger sites
• Sidenotes Guide - Learn TufteCMS's signature feature for adding depth
• Customization Guide - Make the framework reflect your unique vision
• Documentation Index - Complete overview of all guides and features

---

Remember: TufteCMS optimizes for human reading time over writing time. Every feature serves the goal of making your content more discoverable, connected, and contemplative.