kennethreitz.org/docs/content-structure.md

# Content Structure

*Organizing your markdown files for maximum discoverability*

TufteCMS transforms your directory structure into URL routes while providing intelligent content organization and cross-referencing capabilities.

> This guide assumes you've completed the [getting started](/docs/getting-started) setup. For template customization, see the [customization guide](/docs/customization).

## URL Mapping

TufteCMS follows a simple pattern: filesystem paths become URL paths.

```
data/index.md                → /
data/essays/index.md          → /essays
data/essays/hello-world.md    → /essays/hello-world
docs/getting-started.md → /docs/getting-started
data/projects/tuftecms.md    → /projects/tuftecms
```

## Recommended Structure

```
data/
├── index.md              # Homepage - your digital garden entrance
├── essays/               # Long-form contemplative writing
│   ├── index.md         # Essays collection page
│   ├── 2025-01-01-programming-as-practice.md
│   ├── 2025-01-15-consciousness-and-code.md
│   └── 2025-02-01-recursive-thinking.md
├── notes/               # Shorter observations and thoughts  
│   ├── index.md         # Notes collection page
│   ├── daily-reflections.md
│   └── reading-responses.md
├── projects/            # Work portfolio and case studies
│   ├── index.md         # Projects overview
│   ├── tuftecms.md     # Individual project pages
│   └── requests-library.md
├── docs/               # Framework documentation
│   ├── index.md
│   ├── getting-started.md
│   └── customization.md
└── static/            # Images, assets, downloads
    ├── images/
    ├── css/
    └── downloads/
```

## File Naming Conventions

### Date-based Posts

For chronological content like essays or blog posts:

```
YYYY-MM-DD-slug.md

Examples:
2025-01-15-python-as-english.md
2025-02-01-consciousness-research.md
2025-03-10-recursive-loops.md
```

The date in the filename is used for:
- Automatic chronological sorting
- Archive organization  
- Publishing date extraction
- URL generation (optional)

### Topic-based Pages

For reference material or evergreen content:

```
descriptive-slug.md

Examples:
getting-started.md
sidenotes-guide.md
customization.md
api-reference.md
```

### Index Pages

Each directory should have an `index.md` that serves as:
- Collection overview
- Navigation hub
- Context setting for the section

```markdown
# Essays

*Explorations of consciousness, technology, and human flourishing*

This collection documents my journey exploring how technology can serve human consciousness rather than exploit it.

## Recent Essays

[The content system automatically shows recent posts here]

## Themes

- **Programming as Practice** - Code as contemplative discipline
- **AI Consciousness** - Collaborative thinking with digital minds  
- **Algorithmic Critique** - How optimization consumes human values
```

## Automatic Metadata Extraction

TufteCMS intelligently extracts metadata from your content structure:

### Title Extraction

```markdown
# Programming as Spiritual Practice

Content starts here...
```

**Title Sources (in priority order):**
1. First H1 heading (`# Title`)
2. Filename converted to title case (`programming-as-practice.md` → "Programming as Practice")

### Date Extraction

**Filename patterns:**
```
2025-01-15-programming-as-practice.md  → January 15, 2025
2025-02-consciousness-research.md      → February 2025  
programming-basics.md                  → No date (evergreen)
```

**Italic date patterns in content:**
```markdown
# My Essay

*January 2025*

Content here...
```

### Automatic Content Analysis

TufteCMS automatically calculates:

- **Word count** - From rendered content
- **Reading time** - Estimated at ~200 words per minute  
- **Cross-references** - Internal links between pages
- **Sidenotes extraction** - Marginal annotations for indexing
- **Quotes extraction** - Blockquotes for the quotes index
- **Terms extraction** - Key concepts for the terms index
- **Outline extraction** - Heading structure for navigation

## Content Types

### Essays

Long-form contemplative writing exploring ideas in depth:

```
data/essays/
├── index.md
├── 2025-01-01-introduction.md
├── 2025-01-15-deep-exploration.md
└── 2025-02-01-synthesis.md
```

Characteristics:
- 2000-5000 words typically
- Rich with sidenotes for depth
- Extensive cross-referencing
- Philosophical or technical insights

### Notes

Shorter observations, responses, daily thoughts:

```
data/notes/
├── index.md  
├── daily-observations.md
├── book-responses.md
└── quick-insights.md
```

Characteristics:
- 200-1000 words typically
- More immediate, less polished
- Quick capture of insights
- Links to related essays

### Projects

Portfolio items, case studies, software documentation:

```
data/projects/
├── index.md
├── tuftecms.md
├── requests-library.md
└── consciousness-research.md
```

Characteristics:
- Technical documentation
- Process narratives  
- Impact analysis
- Links to code/demos

### Documentation

Framework guides, tutorials, reference material:

```
docs/
├── index.md
├── getting-started.md
├── content-structure.md
└── deployment.md
```

Characteristics:
- Step-by-step instructions
- Code examples
- Reference information
- Troubleshooting guides

## Cross-Reference Strategy

### Internal Linking

Link between content using clean URLs:

```markdown
This builds on ideas from [Programming as Practice](/essays/programming-as-practice).

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

Related thoughts in my [daily notes](/notes/recursive-thinking).
```

### Contextual References

Add context to links for better understanding:

```markdown
The concept of [recursive loops in consciousness](/essays/recursive-loops) appears throughout this work.

As I explored in [the algorithm eats series](/essays/algorithm-eats-virtue), optimization creates destructive feedback cycles.
```

### Backlink Integration

TufteCMS automatically tracks incoming references and can surface them in templates. Consider how each piece fits into the larger web of ideas.

## Content Flow Patterns

### Idea Development

1. **Capture** in notes (quick, unpolished)  
2. **Develop** in essays (deep exploration)
3. **Apply** in projects (practical implementation)
4. **Document** in docs (systematic explanation)

### Cross-Pollination

- Essays reference practical projects
- Projects link back to philosophical foundations  
- Notes capture responses to both
- Documentation ties everything together

### Temporal Organization

- **Archive view**: Chronological browsing
- **Topic view**: Thematic clustering
- **Connection view**: Relationship mapping
- **Random view**: Serendipitous discovery

## Growth Strategies

### Start Small

Begin with a few well-crafted pieces:
- Homepage introduction
- 2-3 essays exploring core themes
- Basic project documentation
- Simple about/contact pages

### Expand Systematically

Add content in coherent clusters:
- Complete a series before starting another
- Build out documentation as you develop ideas
- Let cross-references emerge organically
- Maintain consistent voice and quality

### Optimize for Discovery

- Rich internal linking between related ideas
- Meaningful file names and URLs
- Strategic use of sidenotes for depth
- Clear title structure with H1 headings

## Next Steps

With your content well-organized:

- **Add depth with [sidenotes](/docs/sidenotes)** - Learn TufteCMS's signature marginal annotations
- **Customize your templates** - Follow the [customization guide](/docs/customization) to reflect your unique style  
- **Deploy your site** - Use the [deployment guide](/docs/deployment) for production hosting
- **Explore advanced features** - Return to the [documentation index](/docs) for specialized topics

---

*Remember: The goal isn't volume but coherence. Every piece should contribute to a larger understanding, with connections that help readers navigate between ideas naturally.*