docs refactor
All checks were successful
All checks were successful
This commit is contained in:
629
docs/content/deployment/local-development.md
Normal file
629
docs/content/deployment/local-development.md
Normal file
@ -0,0 +1,629 @@
|
||||
---
|
||||
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. 🚀
|
Reference in New Issue
Block a user