docs refactor
All checks were successful
Datadog Software Composition Analysis / Datadog SBOM Generation and Upload (push) Successful in 52s
Datadog Secrets Scanning / Datadog Static Analyzer (push) Successful in 1m1s
Datadog Static Analysis / Datadog Static Analyzer (push) Successful in 5m50s

This commit is contained in:
2025-10-09 18:21:23 -04:00
parent c9a3a21f07
commit ad81d7f3db
39 changed files with 12551 additions and 1037 deletions

View File

@ -0,0 +1,441 @@
---
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.