---
version: "1.0"
date: "2025-01-15"
author: "DWS Foldsite Team"
title: "Foldsite Documentation"
description: "Turn your folders into beautiful websites with zero configuration"
summary: "Welcome to Foldsite - a modern static/dynamic site generator that transforms your file structure into a navigable website. Focus on content, not configuration."
quick_tips:
  - "Your folder structure IS your site structure - no complex routing needed"
  - "Templates cascade automatically - create them where you need them"
  - "Start with just markdown files - add templates and styles later"
---

# Welcome to Foldsite

**Foldsite** is a static/dynamic site generator that lets you focus on what matters: **your content**. Drop markdown files into folders, add templates for customization, and Foldsite handles the rest.

> *"It's your Internet. Take it back."*
> — [DWS (Dubey Web Services)](https://dws.rip)

## What Makes Foldsite Different?

### Folders → Site Structure
Your directory layout becomes your website structure automatically. No routing configuration, no complex build steps. Create a folder, drop in a markdown file, and it's live.

```
content/
├── about.md              →  /about
├── blog/
│   ├── post-1.md        →  /blog/post-1.md
│   └── post-2.md        →  /blog/post-2.md
└── photos/
    └── vacation/         →  /photos/vacation
```

### Template System That Makes Sense
Templates cascade through your directory tree. Create specific templates for individual files, or general templates that apply to entire sections:

- `__file.md.html` - Template for all markdown files
- `__folder.md.html` - Template for folders containing markdown
- `__folder.image.html` - Template for photo galleries
- Custom templates for specific pages

### Powerful Helper Functions
Access content dynamically from your templates using built-in Jinja2 helpers:

```jinja
{# List recent blog posts #}
{% for post in get_recent_posts(limit=5, folder='blog') %}
  <a href="/{{ post.path }}">{{ post.title }}</a>
{% endfor %}

{# Show navigation breadcrumbs #}
{% for crumb in generate_breadcrumbs(currentPath) %}
  <a href="{{ crumb.url }}">{{ crumb.title }}</a>
{% endfor %}
```

## Quick Start

### 1. Install and Run

```bash
# Clone the repository
git clone https://github.com/DWSresearch/foldsite
cd foldsite

# Install dependencies
pip install -r requirements.txt

# Run the development server
python main.py --config config.toml
```

Visit `http://localhost:8081` to see your site!

### 2. Create Your First Page

```bash
# Create a content directory
mkdir -p my-site/content

# Write your first page
echo "# Hello World" > my-site/content/index.md
```

### 3. Customize with Templates

```bash
# Create a basic template structure
mkdir -p my-site/templates my-site/styles

# Add a base template (see Templates section for examples)
```

## Common Use Cases

### Personal Blog
Perfect for sharing your thoughts with automatic post discovery, tagging, and chronological sorting.

### Photo Gallery
Built-in image handling with EXIF data extraction, thumbnail generation, and gallery views.

### Documentation Site
Hierarchical content organization with automatic navigation and sibling page discovery.

### Portfolio Site
Showcase projects with flexible templates that adapt to your content type.

## Documentation Sections

### [About Foldsite](about.md)
Learn about the philosophy behind Foldsite and why it was created.

### [Directory Structure](directory-structure.md)
Understanding how to organize your content, templates, and styles.

### [Deployment](deployment/)
Get your Foldsite running locally, in Docker, or production environments.

### [Templates](templates/)
Master the template system - from basics to advanced hierarchical templates.

### [Styles](styles/)
Learn how CSS cascades through your site structure.

### [Template Recipes](recipes/)
Ready-to-use examples for blogs, galleries, documentation sites, and more.

### [Theme Gallery](theme-gallery.md)
Explore community-created themes and templates.

### [Explore Foldsites](explore.md)
See real-world examples of Foldsite in action.

### [Develop Foldsite](develop/)
Contributing to Foldsite development.

### [Support](support.md)
Get help and connect with the community.

## Why Foldsite Exists

Foldsite is part of the **DWS (Dubey Web Services)** mission to help people reclaim their corner of the internet. In an era of complex CMSs and heavy frameworks, Foldsite brings simplicity back:

- **Own your content** - Just files and folders on your filesystem
- **Control your presentation** - Templates and styles that make sense
- **Host anywhere** - Static files or dynamic Python server
- **Zero lock-in** - Your markdown works everywhere

## Philosophy

1. **Content is king** - Your folders and files are the source of truth
2. **Convention over configuration** - Sensible defaults, customize when needed
3. **Progressive enhancement** - Start simple, add complexity only where needed
4. **Developer friendly** - Clear APIs, helpful error messages, debug tools

## Next Steps

- **New users**: Start with [Directory Structure](directory-structure.md) to understand the basics
- **Building a blog**: Jump to [Blog Site Recipe](recipes/blog-site.md)
- **Creating themes**: Read the [Templates Guide](templates/)
- **Deploying**: Check [Deployment Options](deployment/)

Ready to turn your folders into a website? Let's get started!