foldsite/docs/content/directory-structure.md

---
version: "1.0"
date: "2025-01-15"
author: "DWS Foldsite Team"
title: "Directory Structure Guide"
description: "Understanding how to organize your Foldsite project"
summary: "Learn how Foldsite's directory structure works - where to put content, templates, and styles for maximum flexibility and power."
quick_tips:
  - "content/ is where all your pages and media live"
  - "templates/ cascade down through subdirectories for hierarchical theming"
  - "Hidden files (starting with ___) are ignored by Foldsite"
---

# Directory Structure Guide

Understanding Foldsite's directory structure is essential to using it effectively. The beauty of Foldsite is that **your folder structure IS your site structure**.

## The Three Core Directories

Every Foldsite project has three main directories:

```
my-site/
├── content/       # Your pages, posts, images, and files
├── templates/     # HTML templates using Jinja2
└── styles/        # CSS stylesheets
```

### content/ - Your Website Content

This is where everything your visitors see lives. Every file and folder in here becomes part of your website.

**Example structure:**

```
content/
├── index.md                    # Homepage (/)
├── about.md                    # About page (/about.md)
├── contact.md                  # Contact page (/contact.md)
├── blog/                       # Blog section (/blog)
│   ├── 2024-01-15-first-post.md
│   ├── 2024-02-20-second-post.md
│   └── archives/
│       └── 2023-recap.md
├── photos/                     # Photo galleries
│   ├── vacation/
│   │   ├── IMG_001.jpg
│   │   ├── IMG_002.jpg
│   │   └── IMG_003.jpg
│   └── family/
│       ├── portrait.jpg
│       └── gathering.jpg
└── downloads/                  # Files for download
    ├── resume.pdf
    └── presentation.pptx
```

**How URLs work:**

- `content/index.md` → `http://yoursite.com/`
- `content/about.md` → `http://yoursite.com/about.md`
- `content/blog/first-post.md` → `http://yoursite.com/blog/first-post.md`
- `content/photos/vacation/` → `http://yoursite.com/photos/vacation`

### templates/ - HTML Templates

Templates define how your content is displayed. They mirror your content structure and cascade down through subdirectories.

**Example structure:**

```
templates/
├── base.html                   # Required: Main page wrapper
├── __error.html                # Optional: Custom error page
├── __file.md.html              # Template for all markdown files
├── __folder.md.html            # Template for folders with markdown
├── __folder.image.html         # Template for image galleries
├── blog/
│   └── __file.md.html          # Custom template for blog posts
└── photos/
    └── __folder.image.html     # Custom gallery template for photos
```

**Key template files:**

- `base.html` - **REQUIRED** - Wraps all pages (header, navigation, footer)
- `__file.{category}.html` - Templates for individual files
- `__folder.{category}.html` - Templates for folder views
- `__error.html` - Custom error pages (404, etc.)

### styles/ - CSS Stylesheets

Stylesheets follow the same cascading logic as templates.

**Example structure:**

```
styles/
├── base.css                    # Required: Base styles
├── __file.md.css               # Styles for markdown files
├── __folder.image.css          # Styles for image galleries
├── blog/
│   └── __file.md.css           # Blog-specific styles
└── layouts/
    ├── document.css            # Layout styles
    └── gallery.css             # Gallery layout styles
```

## File Naming Conventions

### Content Files

- **Regular names**: `about.md`, `contact.md`, `my-post.md`
- **Hidden files**: Prefix with `___` to hide from navigation
  - `___draft-post.md` - Won't appear in listings
  - `___notes.md` - Private notes not rendered

### Template Files

Templates use a special naming pattern:

- `__file.{extension}.html` - For individual files
  - `__file.md.html` - All markdown files
  - `__file.jpg.html` - Individual images (rare)

- `__folder.{category}.html` - For folders
  - `__folder.md.html` - Folders containing mostly markdown
  - `__folder.image.html` - Photo gallery folders

- `{specific-name}.html` - For specific pages
  - `index.html` - Only for index.md
  - `about.html` - Only for about.md

### Style Files

Styles follow the same pattern as templates:

- `base.css` - Always loaded
- `__file.md.css` - Loaded for markdown files
- `__folder.image.css` - Loaded for image galleries
- `{specific-path}.css` - Loaded for specific pages

## How File Categories Work

Foldsite automatically categorizes files by extension:

| Category | Extensions | Template Pattern | Use Case |
|----------|-----------|------------------|----------|
| **document** | `.md`, `.txt`, `.html` | `__file.document.html` | Articles, pages |
| **image** | `.jpg`, `.png`, `.gif`, `.svg` | `__file.image.html` | Photos |
| **multimedia** | `.mp4`, `.mp3`, `.webm` | `__file.multimedia.html` | Videos, audio |
| **other** | Everything else | `__file.other.html` | PDFs, downloads |

Folders are categorized by their **most common file type**:

```
photos/          # Mostly images → "image" category
  IMG_001.jpg
  IMG_002.jpg
  notes.txt      # Ignored for categorization

blog/            # Mostly markdown → "document" category
  post-1.md
  post-2.md
  header.jpg     # Ignored for categorization
```

## Template and Style Discovery

Foldsite uses a **hierarchical discovery system**. When rendering a page, it searches for templates from most specific to most general.

### Example: Rendering `content/blog/my-post.md`

**Template search order:**

1. `templates/blog/my-post.html` - Specific file template
2. `templates/blog/__file.md.html` - Blog folder markdown template
3. `templates/blog/__file.document.html` - Blog folder document template
4. `templates/__file.md.html` - Root markdown template
5. `templates/__file.document.html` - Root document template
6. `templates/__file.html` - Generic file template

**First match wins.**

### Example: Rendering `content/photos/vacation/` folder

**Template search order:**

1. `templates/photos/vacation/__folder.html` - Specific folder template
2. `templates/photos/__folder.image.html` - Photo folder image template
3. `templates/__folder.image.html` - Root image folder template
4. `templates/__folder.html` - Generic folder template

**Style discovery works the same way**, building a list of all matching styles from most specific to most general.

## Configuration File

The `config.toml` file tells Foldsite where your directories are:

```toml
[paths]
content_dir = "/path/to/content"
templates_dir = "/path/to/templates"
styles_dir = "/path/to/styles"

[server]
listen_address = "0.0.0.0"
listen_port = 8081
admin_browser = false
admin_password = "change-me"
max_threads = 4
debug = false
access_log = true
```

### Key Configuration Options

**paths:**
- `content_dir` - Absolute path to content folder
- `templates_dir` - Absolute path to templates folder
- `styles_dir` - Absolute path to styles folder

**server:**
- `listen_address` - IP to bind to (`0.0.0.0` for all interfaces)
- `listen_port` - Port number (default 8081)
- `admin_browser` - Enable file manager UI (true/false)
- `admin_password` - Password for file manager (if enabled)
- `max_threads` - Number of worker threads
- `debug` - Enable debug mode (shows template discovery)
- `access_log` - Log HTTP requests

## Special Files and Folders

### Hidden Content (`___` prefix)

Files and folders starting with three underscores are ignored:

```
content/
├── public-post.md        # ✓ Visible
├── ___draft-post.md      # ✗ Hidden
├── blog/                 # ✓ Visible
│   └── article.md
└── ___notes/             # ✗ Hidden (entire folder)
    └── ideas.md
```

Use this for:
- Draft posts
- Private notes
- Work-in-progress content
- Template testing

### Index Files

`index.md` files serve as folder landing pages:

```
content/
├── index.md              # Homepage: /
└── blog/
    ├── index.md          # Blog index: /blog or /blog/
    ├── post-1.md         # Post: /blog/post-1.md
    └── post-2.md         # Post: /blog/post-2.md
```

Without an `index.md`, folders display using the `__folder.*` template.

## Practical Examples

### Minimal Setup

Simplest possible Foldsite:

```
my-site/
├── content/
│   └── index.md
├── templates/
│   ├── base.html
│   └── __file.md.html
└── styles/
    └── base.css
```

### Blog Site

Typical blog structure:

```
blog-site/
├── content/
│   ├── index.md                  # Homepage
│   ├── about.md                  # About page
│   └── posts/
│       ├── 2024-01-post.md
│       ├── 2024-02-post.md
│       └── ___draft.md           # Hidden draft
├── templates/
│   ├── base.html
│   ├── __file.md.html            # Default post template
│   ├── __folder.md.html          # Post listing
│   └── index.html                # Custom homepage
└── styles/
    ├── base.css
    ├── __file.md.css
    └── __folder.md.css
```

### Photo Portfolio

Photography site structure:

```
portfolio/
├── content/
│   ├── index.md
│   └── galleries/
│       ├── landscape/
│       │   ├── IMG_001.jpg
│       │   └── IMG_002.jpg
│       ├── portrait/
│       │   └── photos...
│       └── urban/
│           └── photos...
├── templates/
│   ├── base.html
│   ├── __folder.image.html       # Gallery template
│   └── galleries/
│       └── __folder.image.html   # Custom for galleries
└── styles/
    ├── base.css
    └── __folder.image.css
```

### Documentation Site

Hierarchical documentation:

```
docs-site/
├── content/
│   ├── index.md
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── configuration.md
│   │   └── first-steps.md
│   ├── guides/
│   │   ├── basics.md
│   │   └── advanced.md
│   └── api/
│       ├── overview.md
│       └── reference.md
├── templates/
│   ├── base.html
│   ├── __file.md.html
│   └── __folder.md.html
└── styles/
    ├── base.css
    └── layouts/
        └── document.css
```

## Best Practices

### 1. Organize Content Logically

Your folder structure should make sense to humans:

```
✓ Good:
content/
├── blog/
├── projects/
└── about.md

✗ Confusing:
content/
├── stuff/
├── things/
└── misc/
```

### 2. Use Descriptive Names

File and folder names become URLs and navigation labels:

```
✓ Good:
getting-started.md
python-tutorial.md
2024-year-review.md

✗ Poor:
page1.md
doc.md
tmp.md
```

### 3. Keep Templates DRY

Don't duplicate templates. Use inheritance and the cascade:

```
✓ Good:
templates/
├── base.html                    # Shared structure
├── __file.md.html               # All markdown files
└── blog/
    └── __file.md.html           # Only blog-specific changes

✗ Redundant:
templates/
├── base.html
├── about.html                   # Unnecessary if using __file.md.html
├── contact.html                 # Unnecessary if using __file.md.html
└── ...
```

### 4. Use Hidden Files for Work in Progress

Keep drafts and private notes out of production:

```
content/
├── published-post.md
├── ___draft-post.md           # Hidden
└── ___notes/                  # Hidden folder
    └── ideas.md
```

## Next Steps

Now that you understand the directory structure:

- [Learn about Templates](templates/) - Master the template system
- [Explore Styles](styles/) - Understand CSS cascading
- [See Recipes](recipes/) - Ready-to-use examples
- [Deploy Your Site](deployment/) - Get it online

The directory structure is the foundation of Foldsite. Master it, and everything else becomes intuitive.