foldsite/docs/content/index.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	Foldsite Documentation	Turn your folders into beautiful websites with zero configuration	Welcome to Foldsite - a modern static/dynamic site generator that transforms your file structure into a navigable website. Focus on content, not configuration.	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)

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:

{# 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

# 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

# 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

# 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

Learn about the philosophy behind Foldsite and why it was created.

Directory Structure

Understanding how to organize your content, templates, and styles.

Deployment

Get your Foldsite running locally, in Docker, or production environments.

Templates

Master the template system - from basics to advanced hierarchical templates.

Styles

Learn how CSS cascades through your site structure.

Template Recipes

Ready-to-use examples for blogs, galleries, documentation sites, and more.

Theme Gallery

Explore community-created themes and templates.

Explore Foldsites

See real-world examples of Foldsite in action.

Develop Foldsite

Contributing to Foldsite development.

Support

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 to understand the basics
• Building a blog: Jump to Blog Site Recipe
• Creating themes: Read the Templates Guide
• Deploying: Check Deployment Options

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