foldsite/docs/content/deployment/local-development.md

---
version: "1.0"
date: "2025-01-15"
author: "DWS Foldsite Team"
title: "Local Development"
description: "Running Foldsite on your local machine for development"
summary: "Complete guide to setting up and running Foldsite locally for the fastest development workflow."
quick_tips:
  - "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**
```bash
# 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](https://www.python.org/downloads/)

**pip (Python package manager)**
```bash
# Check pip version
pip --version

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

**Git (recommended)**
```bash
git --version
```

### Optional but Recommended

**Virtual environment support**
```bash
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)**
```bash
# Clone the repository
git clone https://github.com/DWSresearch/foldsite.git
cd foldsite
```

**Option B: Download ZIP**
```bash
# 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:

```bash
# 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

```bash
# 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:
```bash
# 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:

```bash
# 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:

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

Edit `my-site-config.toml`:

```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:**
```bash
# macOS/Linux:
cd my-site && pwd

# Windows:
cd my-site && cd
```

## Running Foldsite

### Start the Server

```bash
# 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

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

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

# My New Blog Post

This is my latest post!
```

```bash
# 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

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

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

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

### Working with Styles

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

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

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

```bash
# 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:

```toml
[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

```bash
# 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

```bash
# 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:

```bash
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:

```bash
# 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:**
```json
{
    "files.associations": {
        "*.html": "jinja-html"
    },
    "editor.formatOnSave": true
}
```

### Vim/Neovim

Add to `.vimrc` or `init.vim`:
```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:
```toml
[server]
listen_port = 8082
```

**Solution 2:** Find and kill process:
```bash
# Find process using port 8081
lsof -i :8081

# Kill it
kill -9 <PID>
```

### Module Not Found

```
ModuleNotFoundError: No module named 'flask'
```

**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# Enable debug mode
# Edit config.toml
[server]
debug = true

# Restart Foldsite
# Check console output
```

### Permission Denied

```
PermissionError: [Errno 13] Permission denied
```

**Solution:**
```bash
# 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:

```toml
[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](../templates/)** - Learn the template system
- **[Template Helpers](../templates/template-helpers.md)** - Explore helper functions
- **[Recipes](../recipes/)** - Copy working examples
- **[Docker Deployment](docker.md)** - Test in container
- **[Production Deployment](production.md)** - 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. 🚀