Development Guide

Quick Start

First Time Setup

# Install Ruby dependencies
bundle install

Development Servers

1. Full Server (with 404 testing)

./serve.sh

• Port: 4002
• URL: http://localhost:4002
• Features: Custom 404 page handling, mimics GitHub Pages
• Use when: Testing 404 page or full site behavior

2. Jekyll Server (with live reload)

./serve-jekyll.sh

• Port: 4002
• URL: http://localhost:4002
• Features: Live reload, faster development
• Use when: Quick development, content changes

Testing the 404 Page

With serve.sh (Python server)

./serve.sh

Then visit:

• Direct: http://localhost:4002/404.html
• Test 404: http://localhost:4002/missing-page
• Test 404: http://localhost:4002/any/invalid/path

With Jekyll

./serve-jekyll.sh

Then visit:

• Direct: http://localhost:4002/404.html
• Note: Jekyll’s built-in server doesn’t automatically serve 404.html for missing pages

Manual Commands

Build Site

bundle exec jekyll build

Output: _site/ directory

Serve with Jekyll

bundle exec jekyll serve --port 4002

Serve with Jekyll + Live Reload

bundle exec jekyll serve --port 4002 --livereload

Serve with Python (custom 404)

python3 dev_server.py

File Structure

lookinglass-website/
├── serve.sh              # Jekyll build + Python server (404 support)
├── serve-jekyll.sh       # Jekyll server only (live reload)
├── dev_server.py         # Python server with custom 404 handling
├── _config.yml           # Jekyll configuration
├── _layouts/             # Page layouts
├── _includes/            # Reusable components
├── assets/               # CSS, JS, images, icons
├── *.html                # Site pages
└── _site/                # Generated site (git ignored)

Port Configuration

All development servers use port 4002 to avoid conflicts with other projects:

• dogwalking-website: port 4001
• lookinglass-website: port 4002
• dripdoc-website: port 4003 (if needed)

To change the port, edit:

• dev_server.py: Change PORT = 4002
• serve-jekyll.sh: Change --port 4002

Troubleshooting

Port Already in Use

# Find process using port 4002
lsof -ti:4002

# Kill the process
kill -9 $(lsof -ti:4002)

Jekyll Build Errors

# Clean and rebuild
bundle exec jekyll clean
bundle exec jekyll build

Bundle Install Issues

# Update bundler
gem install bundler

# Install dependencies
bundle install

Python Server Not Starting

# Ensure _site directory exists
bundle exec jekyll build

# Run Python server
python3 dev_server.py

Deployment

The site automatically deploys to GitHub Pages when you push to the main branch.

Manual Deployment Check

# Build the site
bundle exec jekyll build

# Check _site directory
ls -la _site/

# Verify 404.html exists
cat _site/404.html

Tips

1. Use serve.sh when testing the complete site including 404 pages
2. Use serve-jekyll.sh for quick content editing with live reload
3. Test 404 page before deploying to production
4. Check mobile responsiveness at http://localhost:4002 on your phone (same network)
5. Clear browser cache if changes don’t appear (Cmd+Shift+R on Mac)