foldsite/docs/content/deployment/local-development.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	Local Development	Running Foldsite on your local machine for development	Complete guide to setting up and running Foldsite locally for the fastest development workflow.	Local development gives instant feedback - no build step needed Use debug mode to see template discovery and errors clearly Changes to content and templates appear immediately on refresh

Local Development

Running Foldsite locally is the fastest way to develop your site. Changes to content and templates appear instantly without any build process.

Prerequisites

Required Software

Python 3.10 or higher

# Check your Python version
python3 --version

# Should output: Python 3.10.x or higher

If you don't have Python 3.10+:

• macOS: brew install python3
• Ubuntu/Debian: sudo apt install python3.10
• Windows: Download from python.org

pip (Python package manager)

# Check pip version
pip --version

# If missing, install
python3 -m ensurepip --upgrade

Git (recommended)

git --version

Optional but Recommended

Virtual environment support

python3 -m venv --help

Text editor with syntax highlighting

• VS Code (recommended)
• Sublime Text
• Vim/Neovim
• Any editor you prefer

Installation

Step 1: Get Foldsite

Option A: Clone with Git (recommended)

# Clone the repository
git clone https://github.com/DWSresearch/foldsite.git
cd foldsite

Option B: Download ZIP

# Download latest release
wget https://github.com/DWSresearch/foldsite/archive/main.zip
unzip main.zip
cd foldsite-main

Step 2: Create Virtual Environment

Using a virtual environment keeps dependencies isolated:

# Create virtual environment
python3 -m venv venv

# Activate it
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

# Your prompt should now show (venv)

Why virtual environment?

• Isolates project dependencies
• Prevents conflicts with system Python
• Easy to recreate or remove
• Professional Python practice

Step 3: Install Dependencies

# Ensure pip is up to date
pip install --upgrade pip

# Install Foldsite dependencies
pip install -r requirements.txt

Dependencies installed:

• Flask - Web framework
• Jinja2 - Template engine
• mistune - Markdown parser
• python-frontmatter - YAML frontmatter parsing
• Pillow - Image processing
• Gunicorn - WSGI server

Troubleshooting:

If you see compilation errors:

# Install build tools

# macOS:
xcode-select --install

# Ubuntu/Debian:
sudo apt install python3-dev build-essential

# Then retry:
pip install -r requirements.txt

Step 4: Set Up Your Content

Create your site directory structure:

# Create your site directories
mkdir -p my-site/content
mkdir -p my-site/templates
mkdir -p my-site/styles

# Create a basic index page
echo "# Welcome to My Site" > my-site/content/index.md

# Copy example templates to start
cp -r example_site/template/* my-site/templates/
cp -r example_site/style/* my-site/styles/

Step 5: Configure Foldsite

Create a configuration file:

# Copy example config
cp config.toml my-site-config.toml

Edit my-site-config.toml:

[paths]
content_dir = "/absolute/path/to/my-site/content"
templates_dir = "/absolute/path/to/my-site/templates"
styles_dir = "/absolute/path/to/my-site/styles"

[server]
listen_address = "127.0.0.1"  # Only accessible from your machine
listen_port = 8081
admin_browser = false          # Disable admin interface for now
max_threads = 4
debug = true                   # Enable debug mode for development
access_log = true

Important: Use absolute paths in development to avoid confusion.

Find absolute path:

# macOS/Linux:
cd my-site && pwd

# Windows:
cd my-site && cd

Running Foldsite

Start the Server

# Make sure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Run Foldsite
python main.py --config my-site-config.toml

Expected output:

[2025-01-15 10:30:45] [INFO] Starting Foldsite server
[2025-01-15 10:30:45] [INFO] Content directory: /path/to/my-site/content
[2025-01-15 10:30:45] [INFO] Templates directory: /path/to/my-site/templates
[2025-01-15 10:30:45] [INFO] Listening on http://127.0.0.1:8081

Visit Your Site

Open your browser to:

http://localhost:8081

You should see your site!

Stop the Server

Press Ctrl+C in the terminal where Foldsite is running.

Development Workflow

The Edit-Refresh Cycle

Foldsite has no build step. Changes appear immediately:

1. Edit content - Modify markdown files
2. Save file - Ctrl+S / Cmd+S
3. Refresh browser - F5 or Cmd+R
4. See changes instantly

What updates live:

• Content (markdown files)
• Templates (HTML files)
• Styles (CSS files)
• Configuration (requires restart)

Example Workflow

Scenario: Adding a blog post

# 1. Create new post
vim my-site/content/blog/my-new-post.md

---
title: "My New Blog Post"
date: "2025-01-15"
tags: ["tutorial", "foldsite"]
---

# My New Blog Post

This is my latest post!

# 2. Save file and switch to browser
# 3. Visit http://localhost:8081/blog/my-new-post.md
# 4. See your post rendered immediately

No restart needed!

Working with Templates

# 1. Edit template
vim my-site/templates/__file.md.html

<!-- Add a new section -->
<article>
    <header>
        <h1>{{ metadata.title }}</h1>
        <time>{{ metadata.date }}</time>
    </header>

    {{ content|safe }}

    <!-- NEW: Add related posts -->
    {% set related = get_related_posts(currentPath, limit=3) %}
    {% if related %}
        <aside class="related">
            <h3>Related Posts</h3>
            {% for post in related %}
                <a href="{{ post.url }}">{{ post.title }}</a>
            {% endfor %}
        </aside>
    {% endif %}
</article>

# 2. Save and refresh browser
# 3. See related posts section appear

Working with Styles

# 1. Edit CSS
vim my-site/styles/base.css

/* Add new styles */
.related {
    margin-top: 2rem;
    padding: 1rem;
    background: #f5f5f5;
    border-radius: 4px;
}

.related h3 {
    margin-bottom: 0.5rem;
}

# 2. Save and hard refresh (Cmd+Shift+R / Ctrl+Shift+R)
# 3. See styled related posts

Debug Mode

Enable debug mode for helpful development information:

[server]
debug = true

What debug mode shows:

• Template discovery process
• Which templates were considered
• Which template was chosen
• Detailed error messages with stack traces
• Template variables and context

Example debug output:

When visiting a page, console shows:

[DEBUG] Template search for: blog/my-post.md
[DEBUG] Checking: templates/blog/my-post.html - Not found
[DEBUG] Checking: templates/blog/__file.md.html - Found!
[DEBUG] Using template: templates/blog/__file.md.html
[DEBUG] Available variables: content, metadata, currentPath, styles

View in browser:

With debug mode, error pages show:

• Full Python stack trace
• Template rendering context
• What went wrong and where
• Suggestions for fixes

Common Development Tasks

Creating New Pages

# Simple page
echo "# About Me\n\nI'm a web developer." > my-site/content/about.md

# With frontmatter
cat > my-site/content/projects.md << 'EOF'
---
title: "My Projects"
description: "Things I've built"
---

# My Projects

Here are some things I've worked on...
EOF

Organizing Content

# Create a blog section
mkdir -p my-site/content/blog

# Add posts
for i in {1..5}; do
  cat > my-site/content/blog/post-$i.md << EOF
---
title: "Blog Post $i"
date: "2024-01-$i"
tags: ["example"]
---

# Post $i

Content here...
EOF
done

Testing Template Helpers

Create a test page to experiment:

cat > my-site/content/test.md << 'EOF'
---
title: "Template Helper Test"
---

# Testing Helpers

## Recent Posts
{% for post in get_recent_posts(limit=5) %}
- [{{ post.title }}]({{ post.url }}) - {{ post.date }}
{% endfor %}

## All Tags
{% for tag in get_all_tags() %}
- {{ tag.name }} ({{ tag.count }})
{% endfor %}

## Current Path Info
- Path: {{ currentPath }}
- Metadata: {{ metadata }}
EOF

Visit /test.md to see helper output.

Hiding Work in Progress

Use the ___ prefix:

# Hidden draft
vim my-site/content/___draft-post.md

# Hidden development folder
mkdir my-site/content/___testing

These won't appear in navigation or listings.

Editor Setup

VS Code

Recommended extensions:

• Python (Microsoft)
• Jinja (wholroyd.jinja)
• Markdown All in One (yzhang.markdown-all-in-one)

Settings:

{
    "files.associations": {
        "*.html": "jinja-html"
    },
    "editor.formatOnSave": true
}

Vim/Neovim

Add to .vimrc or init.vim:

" Jinja syntax for .html files
autocmd BufNewFile,BufRead */templates/*.html set filetype=jinja

" Markdown settings
autocmd FileType markdown setlocal spell spelllang=en_us
autocmd FileType markdown setlocal textwidth=80

Troubleshooting

Port Already in Use

Error: [Errno 48] Address already in use

Solution 1: Change port in config:

[server]
listen_port = 8082

Solution 2: Find and kill process:

# Find process using port 8081
lsof -i :8081

# Kill it
kill -9 <PID>

Module Not Found

ModuleNotFoundError: No module named 'flask'

Solution:

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Template Not Found

Exception: Base template not found

Solution:

# Check templates directory exists and has base.html
ls my-site/templates/base.html

# If missing, copy from example
cp example_site/template/base.html my-site/templates/

Changes Not Appearing

Possible causes:

1. Browser cache - Hard refresh (Cmd/Ctrl + Shift + R)
2. Wrong file - Check you're editing the file Foldsite is using
3. Configuration issue - Verify config.toml paths
4. Syntax error - Check console for error messages

Debug:

# Enable debug mode
# Edit config.toml
[server]
debug = true

# Restart Foldsite
# Check console output

Permission Denied

PermissionError: [Errno 13] Permission denied

Solution:

# Fix permissions
chmod -R 755 my-site/

# Or run with correct user
sudo chown -R $USER:$USER my-site/

Performance Tips

Development Speed

Fast iteration:

• Keep browser DevTools open
• Use multiple browser windows for comparison
• Enable auto-reload browser extensions
• Use terminal multiplexer (tmux/screen)

Organize workspace:

Terminal 1: Foldsite server
Terminal 2: Content editing
Terminal 3: Git operations
Browser: Live preview
Editor: Code/templates

Working with Large Sites

If your site has many files:

[server]
max_threads = 8  # Increase workers

Cache considerations:

• Template helpers are cached automatically
• Folder contents cached for 5 minutes
• Recent posts cached for 10 minutes
• Restart server to clear caches

Next Steps

Now that you have local development running:

• Templates Guide - Learn the template system
• Template Helpers - Explore helper functions
• Recipes - Copy working examples
• Docker Deployment - Test in container
• Production Deployment - Go live

Tips from Developers

"Keep the server running in a dedicated terminal. Switch to it to see errors immediately." — Foldsite contributor

"Use ___testing/ folder for experimenting. It's ignored so you can mess around without affecting the site." — Content creator

"Debug mode is your friend. Always enable it in development." — Theme developer

"Create test pages to try helper functions. Much faster than reading docs." — Documentation writer

Happy developing! Local development is where the magic happens. 🚀