--- 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.