foldsite/docs/content/directory-structure.md

version, date, author, title, description, summary, quick_tips

version	date	author	title	description	summary	quick_tips
1.0	2025-01-15	DWS Foldsite Team	Directory Structure Guide	Understanding how to organize your Foldsite project	Learn how Foldsite's directory structure works - where to put content, templates, and styles for maximum flexibility and power.	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:

[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 - Master the template system
• Explore Styles - Understand CSS cascading
• See Recipes - Ready-to-use examples
• Deploy Your Site - Get it online

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