166 lines
5.3 KiB
Markdown
166 lines
5.3 KiB
Markdown
---
|
|
version: "1.0"
|
|
date: "2025-01-15"
|
|
author: "DWS Foldsite Team"
|
|
title: "Foldsite Documentation"
|
|
description: "Turn your folders into beautiful websites with zero configuration"
|
|
summary: "Welcome to Foldsite - a modern static/dynamic site generator that transforms your file structure into a navigable website. Focus on content, not configuration."
|
|
quick_tips:
|
|
- "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)](https://dws.rip)
|
|
|
|
## 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:
|
|
|
|
```jinja
|
|
{# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](about.md)
|
|
Learn about the philosophy behind Foldsite and why it was created.
|
|
|
|
### [Directory Structure](directory-structure.md)
|
|
Understanding how to organize your content, templates, and styles.
|
|
|
|
### [Deployment](deployment/)
|
|
Get your Foldsite running locally, in Docker, or production environments.
|
|
|
|
### [Templates](templates/)
|
|
Master the template system - from basics to advanced hierarchical templates.
|
|
|
|
### [Styles](styles/)
|
|
Learn how CSS cascades through your site structure.
|
|
|
|
### [Template Recipes](recipes/)
|
|
Ready-to-use examples for blogs, galleries, documentation sites, and more.
|
|
|
|
### [Theme Gallery](theme-gallery.md)
|
|
Explore community-created themes and templates.
|
|
|
|
### [Explore Foldsites](explore.md)
|
|
See real-world examples of Foldsite in action.
|
|
|
|
### [Develop Foldsite](develop/)
|
|
Contributing to Foldsite development.
|
|
|
|
### [Support](support.md)
|
|
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](directory-structure.md) to understand the basics
|
|
- **Building a blog**: Jump to [Blog Site Recipe](recipes/blog-site.md)
|
|
- **Creating themes**: Read the [Templates Guide](templates/)
|
|
- **Deploying**: Check [Deployment Options](deployment/)
|
|
|
|
Ready to turn your folders into a website? Let's get started!
|