October 6, 2025

Project Flux - Standard Operating Procedures (SOP)

By Author 5 min read

Project Name: Flux
Document Type: Standard Operating Procedures
Version: 1.0.0
Last Updated: October 6, 2025
Status: Active

Note: This SOP outlines procedures for the Flux project, built with Zola (v0.21.0) and Tailwind CSS v4. While this blog post itself is powered by Eleventy, the guidelines here focus on Flux's Zola-based workflow for consistency.

Table of Contents

  1. Purpose & Scope
  2. Initial Project Setup
  3. Development Environment Setup
  4. Content Creation Workflow
  5. Template Development
  6. Styling with Tailwind CSS v4
  7. Testing Procedures
  8. Build & Deployment Process
  9. Maintenance & Updates
  10. Troubleshooting Guide
  11. Quality Control Checklist

Purpose & Scope

Purpose

This SOP document provides step-by-step procedures for developing, maintaining, and deploying the Flux project, ensuring consistency and quality across all development activities.

Scope

These procedures apply to all team members working on the Flux project, including developers, content creators, and maintainers.

Definitions

  • Zola: Static site generator written in Rust
  • Tailwind CSS v4: Utility-first CSS framework
  • Production Build: Optimized build for deployment
  • Development Build: Unoptimized build for local testing

Initial Project Setup

SOP-001: Creating a New Flux Project

Frequency: One-time (per new installation)
Responsible Role: Lead Developer
Estimated Time: 15-20 minutes

Prerequisites

  • Zola installed (v0.21.0 or later)
  • Node.js (v18.x or later) and npm installed
  • Git installed
  • Text editor/IDE configured

Procedure

Step 1: Install Zola

# macOS (using Homebrew)
brew install zola

# Windows (using Chocolatey)
choco install zola

# Linux (using snap)
snap install zola --edge

# Verify installation
zola --version

Step 2: Create Project Directory

# Create new Zola site
zola init flux

# Navigate to project directory
cd flux

Step 3: Initialize Git Repository

git init
git add .
git commit -m "Initial commit: Zola project setup"

Step 4: Create Project Structure

# Create additional directories
mkdir -p styles
mkdir -p templates/partials
mkdir -p static/{images,fonts,js}
mkdir -p content/{blog,pages}

Step 5: Initialize Node.js Project

npm init -y

Step 6: Install Tailwind CSS v4

npm install -D tailwindcss@^4.0.0 @tailwindcss/postcss@^4.0.0 postcss autoprefixer

Step 7: Create Configuration Files

Create tailwind.config.js:

npx tailwindcss init

Create postcss.config.js:

touch postcss.config.js

Add the following content:

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  }
}

Step 8: Create Tailwind Entry File

Create styles/main.css:

@import "tailwindcss";

Step 9: Update package.json Scripts

Add to package.json:

{
  "scripts": {
    "dev:css": "tailwindcss -i ./styles/main.css -o ./static/css/style.css --watch",
    "build:css": "tailwindcss -i ./styles/main.css -o ./static/css/style.css --minify",
    "dev": "npm run dev:css & zola serve",
    "build": "npm run build:css && zola build"
  }
}

Step 10: Create .gitignore

# Create .gitignore file
cat > .gitignore << EOF
public/
node_modules/
static/css/style.css
.DS_Store
*.log
EOF

Verification:

  • Run zola --version - confirms Zola installation
  • Run npm list tailwindcss - confirms Tailwind installation
  • Directory structure matches specification
  • Git repository initialized successfully

Development Environment Setup

SOP-002: Setting Up Development Environment

Frequency: Once per developer workstation
Responsible Role: Developer
Estimated Time: 10 minutes

Procedure

Step 1: Clone Repository

git clone [repository-url] flux
cd flux

Step 2: Install Node Dependencies

npm install

Step 3: Configure Zola

Edit config.toml:

base_url = "http://127.0.0.1:1111"
title = "Flux"
description = "A modern static site built with Zola and Tailwind CSS"
default_language = "en"
compile_sass = false
minify_html = false
generate_feed = true
build_search_index = true

[markdown]
highlight_code = true
highlight_theme = "base16-ocean-dark"
smart_punctuation = true
external_links_target_blank = true
external_links_no_follow = false

[link_checker]
skip_prefixes = []

[extra]
site_logo = "/images/logo.svg"

Step 4: Start Development Servers

# Terminal 1: Start Tailwind watcher
npm run dev:css

# Terminal 2: Start Zola server
zola serve

Or use concurrent command:

npm run dev

Step 5: Verify Setup

  • Open browser to http://127.0.0.1:1111
  • Verify hot-reloading works
  • Check CSS compiles correctly
  • Confirm no console errors

Verification Checklist:

  • [ ] Repository cloned successfully
  • [ ] Dependencies installed without errors
  • [ ] Zola server running on port 1111
  • [ ] Tailwind CSS compiling and watching
  • [ ] Changes reflect immediately in browser

Content Creation Workflow

SOP-003: Creating a New Blog Post

Frequency: As needed
Responsible Role: Content Creator
Estimated Time: 5 minutes (setup only)

Procedure

Step 1: Create Content File

# Create new blog post file
touch content/blog/YYYY-MM-DD-post-title.md

Step 2: Add Front Matter

Use this template:

+++
title = "Your Post Title"
date = 2025-10-06
description = "A compelling description for SEO (150-160 characters)"
draft = false

[taxonomies]
tags = ["tag1", "tag2", "tag3"]
categories = ["category"]

[extra]
author = "Author Name"
featured_image = "/images/posts/post-slug.jpg"
reading_time = 5
+++

Your content starts here...

Step 3: Write Content

Follow these guidelines:

  • Use semantic headings (## for H2, ### for H3, etc.)
  • Include alt text for images: ![Alt text](/path/to/image.jpg)
  • Use code blocks with language: ```rust
  • Keep paragraphs concise (3-4 sentences)
  • Add internal links where relevant

Step 4: Add Images (if applicable)

# Copy image to static directory
cp /path/to/image.jpg static/images/posts/

# Optimize image before committing
# Use tools like ImageOptim, TinyPNG, or Squoosh

Step 5: Preview Post

# Ensure dev server is running
zola serve

# Navigate to post in browser
# URL: http://127.0.0.1:1111/blog/post-title/

Step 6: Review Checklist

  • [ ] Title is descriptive and SEO-friendly
  • [ ] Description is 150-160 characters
  • [ ] Date is correct
  • [ ] Tags and categories are appropriate
  • [ ] Images have alt text
  • [ ] Links work correctly
  • [ ] No spelling/grammar errors
  • [ ] Post renders correctly on mobile

Step 7: Set Draft Status

For work in progress:

draft = true

For publishing:

draft = false

Step 8: Commit Changes

git add content/blog/YYYY-MM-DD-post-title.md
git add static/images/posts/post-slug.jpg
git commit -m "Add blog post: Post Title"

SOP-004: Creating a Static Page

Frequency: As needed
Responsible Role: Content Creator/Developer
Estimated Time: 10 minutes

Procedure

Step 1: Create Page File

touch content/pages/page-name.md

Step 2: Add Front Matter

+++
title = "Page Title"
description = "Page description for SEO"
template = "page.html"
date = 2025-10-06

[extra]
show_in_nav = true
nav_order = 1
+++

Page content here...

Step 3: Create Custom Template (if needed)

cp templates/page.html templates/custom-page.html
# Edit custom-page.html as needed

Step 4: Preview and Commit

# Preview
zola serve

# Commit
git add content/pages/page-name.md
git commit -m "Add page: Page Name"

Template Development

SOP-005: Creating/Modifying Zola Templates

Frequency: As needed
Responsible Role: Developer
Estimated Time: 30-60 minutes

Procedure

Step 1: Understand Template Hierarchy

Zola uses this template lookup order:

  1. Page-specific template (template = "custom.html")
  2. Section template (section.html)
  3. Default templates (page.html, index.html)

Step 2: Create Base Template

Create templates/base.html:

<!DOCTYPE html>
<html lang="{{ lang }}" class="scroll-smooth">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}{{ config.title }}{% endblock title %}</title>
    <meta name="description" content="{% block description %}{{ config.description }}{% endblock description %}">
    
    <!-- Tailwind CSS -->
    <link rel="stylesheet" href="{{ get_url(path='css/style.css') }}">
    
    <!-- SEO Meta Tags -->
    {% block seo %}{% endblock seo %}
    
    <!-- RSS Feed -->
    <link rel="alternate" type="application/rss+xml" title="{{ config.title }}" href="{{ get_url(path='rss.xml') }}">
</head>
<body class="min-h-screen bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
    {% include "partials/header.html" %}
    
    <main class="container mx-auto px-4 py-8">
        {% block content %}{% endblock content %}
    </main>
    
    {% include "partials/footer.html" %}
    
    {% block extra_js %}{% endblock extra_js %}
</body>
</html>

Step 3: Create Partial Templates

Header (templates/partials/header.html):

<header class="bg-white dark:bg-gray-800 shadow-sm">
    <nav class="container mx-auto px-4 py-4">
        <div class="flex items-center justify-between">
            <a href="{{ get_url(path='/') }}" class="text-2xl font-bold">
                {{ config.title }}
            </a>
            <ul class="flex space-x-6">
                <li><a href="{{ get_url(path='/') }}" class="hover:text-blue-600">Home</a></li>
                <li><a href="{{ get_url(path='/blog') }}" class="hover:text-blue-600">Blog</a></li>
                <li><a href="{{ get_url(path='/about') }}" class="hover:text-blue-600">About</a></li>
            </ul>
        </div>
    </nav>
</header>

Footer (templates/partials/footer.html):

<footer class="bg-gray-100 dark:bg-gray-800 mt-12">
    <div class="container mx-auto px-4 py-8">
        <p class="text-center text-gray-600 dark:text-gray-400">
            © {{ now() | date(format="%Y") }} {{ config.title }}. All rights reserved.
        </p>
    </div>
</footer>

Step 4: Create Page Templates

Index (templates/index.html):

{% extends "base.html" %}

{% block content %}
<section class="py-20">
    <h1 class="text-5xl font-bold text-center mb-8">
        Welcome to {{ config.title }}
    </h1>
    <p class="text-xl text-center text-gray-600 dark:text-gray-400">
        {{ config.description }}
    </p>
</section>

<section class="py-12">
    <h2 class="text-3xl font-bold mb-8">Recent Posts</h2>
    <div class="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
        {% set blog = get_section(path="blog/_index.md") %}
        {% for page in blog.pages | slice(end=6) %}
        <article class="bg-white dark:bg-gray-800 rounded-lg shadow-md overflow-hidden">
            <a href="{{ page.permalink }}">
                <h3 class="text-xl font-semibold p-6">{{ page.title }}</h3>
                <p class="px-6 pb-6 text-gray-600 dark:text-gray-400">
                    {{ page.description }}
                </p>
            </a>
        </article>
        {% endfor %}
    </div>
</section>
{% endblock content %}

Step 5: Test Template

# Start dev server
zola serve

# Check for errors in terminal
# Verify rendering in browser
# Test responsive design
# Validate HTML

Step 6: Commit Changes

git add templates/
git commit -m "Add/update template: [template-name]"

Best Practices:

  • Use semantic HTML5 elements
  • Include ARIA labels for accessibility
  • Keep templates DRY (Don't Repeat Yourself)
  • Use Tailwind utility classes consistently
  • Comment complex template logic
  • Test on multiple screen sizes

Styling with Tailwind CSS v4

SOP-006: Adding Custom Styles

Frequency: As needed
Responsible Role: Developer/Designer
Estimated Time: 15-30 minutes

Procedure

Step 1: Update Tailwind Configuration

Edit tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './templates/**/*.html',
    './content/**/*.md',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
        },
        secondary: {
          500: '#8b5cf6',
          600: '#7c3aed',
        }
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['Fira Code', 'monospace'],
      },
      typography: (theme) => ({
        DEFAULT: {
          css: {
            color: theme('colors.gray.700'),
            a: {
              color: theme('colors.primary.600'),
              '&:hover': {
                color: theme('colors.primary.700'),
              },
            },
          },
        },
        dark: {
          css: {
            color: theme('colors.gray.300'),
            a: {
              color: theme('colors.primary.400'),
            },
          },
        },
      }),
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

Step 2: Add Custom CSS (if needed)

In styles/main.css:

@import "tailwindcss";

/* Custom base styles */
@layer base {
  body {
    @apply font-sans antialiased;
  }
  
  h1, h2, h3, h4, h5, h6 {
    @apply font-bold;
  }
}

/* Custom components */
@layer components {
  .btn-primary {
    @apply px-6 py-3 bg-primary-600 text-white rounded-lg hover:bg-primary-700 transition-colors;
  }
  
  .card {
    @apply bg-white dark:bg-gray-800 rounded-lg shadow-md p-6;
  }
}

/* Custom utilities */
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
}

Step 3: Rebuild CSS

npm run build:css

Step 4: Test Styles

  • Check all pages for visual consistency
  • Test dark mode toggle
  • Verify responsive breakpoints
  • Check hover states and transitions
  • Validate color contrast for accessibility

Step 5: Commit Changes

git add tailwind.config.js styles/main.css
git commit -m "Update Tailwind configuration and custom styles"

SOP-007: Implementing Dark Mode

Frequency: One-time setup
Responsible Role: Developer
Estimated Time: 30 minutes

Procedure

Step 1: Configure Tailwind for Dark Mode

Already set in tailwind.config.js:

darkMode: 'class',

Step 2: Create Dark Mode Toggle

Add to templates/partials/header.html:

<button id="theme-toggle" class="p-2 rounded-lg hover:bg-gray-200 dark:hover:bg-gray-700">
    <svg id="theme-toggle-dark-icon" class="hidden w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
        <path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z"></path>
    </svg>
    <svg id="theme-toggle-light-icon" class="hidden w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
        <path d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"></path>
    </svg>
</button>

Step 3: Add JavaScript

Create static/js/theme.js:

// Theme toggle functionality
const themeToggle = document.getElementById('theme-toggle');
const darkIcon = document.getElementById('theme-toggle-dark-icon');
const lightIcon = document.getElementById('theme-toggle-light-icon');

// Check for saved theme preference or default to system
const theme = localStorage.getItem('theme') || 
              (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');

if (theme === 'dark') {
    document.documentElement.classList.add('dark');
    lightIcon.classList.remove('hidden');
} else {
    darkIcon.classList.remove('hidden');
}

themeToggle.addEventListener('click', function() {
    document.documentElement.classList.toggle('dark');
    
    if (document.documentElement.classList.contains('dark')) {
        localStorage.setItem('theme', 'dark');
        darkIcon.classList.add('hidden');
        lightIcon.classList.remove('hidden');
    } else {
        localStorage.setItem('theme', 'light');
        lightIcon.classList.add('hidden');
        darkIcon.classList.remove('hidden');
    }
});

Step 4: Include Script in Base Template

In templates/base.html:

<script src="{{ get_url(path='js/theme.js') }}" defer></script>

Step 5: Test Dark Mode

  • [ ] Toggle switches between light/dark
  • [ ] Preference persists on page reload
  • [ ] All text remains readable
  • [ ] Images/logos work in both modes
  • [ ] Syntax highlighting works in both modes

Testing Procedures

SOP-008: Pre-Deployment Testing

Frequency: Before every deployment
Responsible Role: QA/Developer
Estimated Time: 30-45 minutes

Procedure

Step 1: Build Production Version

npm run build

Step 2: Visual Testing

  • [ ] Test all pages on desktop (1920x1080)
  • [ ] Test all pages on tablet (768x1024)
  • [ ] Test all pages on mobile (375x667)
  • [ ] Verify all images load correctly
  • [ ] Check for broken layouts
  • [ ] Test dark mode on all pages

Step 3: Functionality Testing

  • [ ] Click all navigation links
  • [ ] Test search functionality
  • [ ] Verify RSS feed generates
  • [ ] Check sitemap.xml exists
  • [ ] Test 404 error page
  • [ ] Verify external links open in new tab

Step 4: Performance Testing

Using Lighthouse (Chrome DevTools):

# Or use CLI
npm install -g lighthouse
lighthouse http://127.0.0.1:1111 --view

Target scores:

  • Performance: 95+
  • Accessibility: 95+
  • Best Practices: 95+
  • SEO: 95+

Step 5: Accessibility Testing

  • [ ] Run axe DevTools scan
  • [ ] Test keyboard navigation
  • [ ] Verify proper heading hierarchy
  • [ ] Check color contrast ratios
  • [ ] Test with screen reader (if available)

Step 6: SEO Testing

  • [ ] Verify meta descriptions on all pages
  • [ ] Check Open Graph tags
  • [ ] Verify Twitter Card tags
  • [ ] Test structured data with Google Rich Results Test
  • [ ] Verify canonical URLs

Step 7: Cross-Browser Testing

Test on:

  • [ ] Chrome (latest)
  • [ ] Firefox (latest)
  • [ ] Safari (latest)
  • [ ] Edge (latest)

Step 8: Link Validation

# Build site first
zola build

# Check for broken links
zola check

Step 9: HTML Validation

Use W3C Validator:

  • Visit https://validator.w3.org/
  • Upload HTML files from public/ directory
  • Fix any errors or warnings

Step 10: Document Test Results

Create test report:

## Test Report - [Date]

### Build Information
- Zola Version: [version]
- Tailwind CSS Version: [version]
- Commit Hash: [hash]

### Test Results
- Visual Testing: PASS/FAIL
- Functionality: PASS/FAIL
- Performance: [scores]
- Accessibility: PASS/FAIL
- SEO: PASS/FAIL
- Cross-Browser: PASS/FAIL

### Issues Found
1. [Issue description]
2. [Issue description]

### Sign-off
Tested by: [Name]
Date: [Date]

Build & Deployment Process

SOP-009: Production Build

Frequency: Before every deployment
Responsible Role: Developer
Estimated Time: 5 minutes

Procedure

Step 1: Pre-Build Checklist

  • [ ] All changes committed to Git
  • [ ] Tests passed (SOP-008)
  • [ ] Content reviewed and approved
  • [ ] Version number updated (if applicable)

Step 2: Update Configuration

Edit config.toml:

base_url = "https://yourdomain.com"
minify_html = true

Step 3: Build CSS

npm run build:css

Verify output:

  • Check static/css/style.css exists
  • File should be minified
  • Check file size is reasonable

Step 4: Build Site

zola build

Step 5: Verify Build

# Check build completed successfully
ls public/

# Verify key files exist
ls public/index.html
ls public/css/style.css
ls public/sitemap.xml
ls public/rss.xml

Step 6: Test Built Site Locally

# Serve the built site
cd public
python3 -m http.server 8000

# Test in browser: http://localhost:8000

Step 7: Check Build Size

du -sh public/

Target: < 10MB (excluding large media)

Step 8: Create Build Tag

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

SOP-010: Deploying to Netlify

Frequency: As needed
Responsible Role: Developer/DevOps
Estimated Time: 10 minutes (initial), 2 minutes (subsequent)

Initial Setup

Step 1: Create netlify.toml

[build]
  command = "npm run build"
  publish = "public"

[build.environment]
  ZOLA_VERSION = "0.21.0"
  NODE_VERSION = "18"

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[headers]]
  for = "/css/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/images/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301

Step 2: Connect Repository

  1. Log in to Netlify
  2. Click "Add new site" > "Import an existing project"
  3. Connect to Git provider
  4. Select repository
  5. Configure build settings (should auto-detect from netlify.toml)

Step 3: Configure Environment

  • Build command: npm run build
  • Publish directory: public

Step 4: Deploy

  • Click "Deploy site"
  • Wait for build to complete
  • Verify deployment

Subsequent Deployments

Automatic Deployment:

# Push to main branch
git push origin main

# Netlify automatically builds and deploys

Manual Deployment:

  1. Navigate to Netlify dashboard
  2. Click "Trigger deploy" > "Deploy site"

Step 5: Verify Deployment

  • [ ] Visit production URL
  • [ ] Check homepage loads
  • [ ] Test navigation
  • [ ] Verify images load
  • [ ] Check mobile responsive
  • [ ] Test search functionality

Step 6: Post-Deployment Monitoring

  • Check Netlify deploy logs for errors
  • Monitor Google Search Console
  • Check analytics for traffic
  • Monitor performance metrics

SOP-011: Deploying to Cloudflare Pages

Frequency: As needed
Responsible Role: Developer/DevOps
Estimated Time: 10 minutes (initial)

Procedure

Step 1: Connect Repository

  1. Log in to Cloudflare Dashboard
  2. Navigate to Pages
  3. Click "Create a project"
  4. Connect Git repository

Step 2: Configure Build

  • Framework preset: None
  • Build command: npm run build && zola build
  • Build output directory: public
  • Root directory: (leave empty)

Step 3: Set Environment Variables

ZOLA_VERSION=0.21.0
NODE_VERSION=18

Step 4: Deploy

  • Click "Save and Deploy"
  • Monitor build progress
  • Verify deployment

Step 5: Configure Custom Domain (Optional)

  1. Go to Custom domains
  2. Add your domain
  3. Update DNS records
  4. Wait for SSL certificate

Maintenance & Updates

SOP-012: Regular Maintenance Tasks

Frequency: Monthly
Responsible Role: Maintainer
Estimated Time: 1-2 hours

Procedure

Step 1: Update Dependencies

# Check for outdated packages
npm outdated

# Update Tailwind CSS
npm update tailwindcss @tailwindcss/postcss

# Update other dependencies
npm update

# Check Zola version
zola --version

# Update Zola if needed (follow official docs)

Step 2: Review and Update Content

  • [ ] Check for outdated information
  • [ ] Update copyright year in footer
  • [ ] Review and respond to comments
  • [ ] Check for broken external links
  • [ ] Update team/about pages

Step 3: Performance Audit

# Run Lighthouse audit
lighthouse https://yourdomain.com --view

# Check Core Web Vitals in Google Search Console

Step 4: Security Review

  • [ ] Review Netlify/Cloudflare security settings
  • [ ] Check SSL certificate validity
  • [ ] Review Content Security Policy
  • [ ] Audit third-party scripts

Step 5: Backup

# Create backup branch
git checkout -b backup-$(date +%Y%m%d)
git push origin backup-$(date +%Y%m%d)

# Export content
cp -r content/ backups/content-$(date +%Y%m%d)/

Step 6: Analytics Review

  • Review traffic patterns
  • Identify popular content
  • Check bounce rates
  • Monitor search rankings
  • Review conversion goals

Step 7: Update Documentation

  • Update README if needed
  • Document any new procedures
  • Update changelog
  • Review and update SOP document

SOP-013: Dependency Updates

Frequency: Quarterly or when security updates available
Responsible Role: Developer
Estimated Time: 30 minutes

Procedure

Step 1: Check Current Versions

# Check npm packages
npm outdated

# Check Zola version
zola --version

# Check latest Zola release
# Visit: https://github.com/getzola/zola/releases

Step 2: Review Changelogs

  • Read Tailwind CSS v4 changelog
  • Review Zola release notes
  • Check for breaking changes
  • Identify new features

Step 3: Update Node Packages

# Update package.json
npm update

# Or update specific package
npm install tailwindcss@latest

# Audit for vulnerabilities
npm audit

# Fix vulnerabilities
npm audit fix

Step 4: Update Zola

# macOS
brew upgrade zola

# Windows
choco upgrade zola

# Linux
snap refresh zola

Step 5: Test After Updates

# Clean build
rm -rf public/
npm run build

# Test locally
zola serve

Step 6: Run Full Test Suite

  • Follow SOP-008 (Pre-Deployment Testing)
  • Check for visual regressions
  • Verify all functionality works
  • Test on multiple browsers

Step 7: Update Documentation

# Update version numbers in README
# Update package.json version
# Update config.toml if needed

Step 8: Commit and Deploy

git add package.json package-lock.json
git commit -m "chore: update dependencies to latest versions"
git push origin main

Rollback Procedure (if issues occur):

# Revert to previous commit
git revert HEAD

# Or checkout previous version
git checkout [previous-commit-hash] package.json package-lock.json
npm install

Troubleshooting Guide

SOP-014: Common Issues and Solutions

Frequency: As needed
Responsible Role: Developer

Issue 1: Tailwind CSS Not Compiling

Symptoms:

  • CSS file not generated
  • Styles not applying
  • Build errors

Solution:

# Step 1: Check if Tailwind is installed
npm list tailwindcss

# Step 2: Reinstall if needed
rm -rf node_modules package-lock.json
npm install

# Step 3: Verify configuration files exist
ls tailwind.config.js postcss.config.js styles/main.css

# Step 4: Check npm scripts in package.json
cat package.json | grep "build:css"

# Step 5: Try manual build
npx tailwindcss -i ./styles/main.css -o ./static/css/style.css

# Step 6: Check for syntax errors in config
node -c tailwind.config.js

Prevention:

  • Always commit package-lock.json
  • Document custom configuration
  • Use version control for config files

Issue 2: Zola Build Fails

Symptoms:

  • zola build command fails
  • Template errors
  • Content parsing errors

Solution:

# Step 1: Check Zola version
zola --version

# Step 2: Run with verbose output
zola build --verbose

# Step 3: Check for template syntax errors
# Look for unclosed tags, missing variables

# Step 4: Validate content front matter
# Check all +++ sections are properly closed

# Step 5: Test individual templates
# Comment out sections to isolate issue

# Step 6: Clear cache and rebuild
rm -rf public/ static/processed_images/
zola build

Common Causes:

  • Unclosed Tera template tags
  • Invalid TOML in front matter
  • Missing required variables
  • Incorrect file paths

Issue 3: Images Not Loading

Symptoms:

  • Broken image icons
  • 404 errors for images
  • Images work locally but not in production

Solution:

# Step 1: Check file path
# Paths should be relative to static/ folder
# Example: /images/photo.jpg (not /static/images/photo.jpg)

# Step 2: Verify file exists
ls static/images/

# Step 3: Check file permissions
chmod 644 static/images/*

# Step 4: Verify image referenced correctly in template
# Use: {{ get_url(path="images/photo.jpg") }}
# Or: /images/photo.jpg

# Step 5: Check base_url in config.toml
# Should match production domain

# Step 6: Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

Issue 4: Dark Mode Not Working

Symptoms:

  • Toggle button doesn't work
  • Theme doesn't persist
  • Styles not applying

Solution:

# Step 1: Check JavaScript file loaded
# Open DevTools Console, look for errors

# Step 2: Verify script tag in base.html
# Should be: <script src="/js/theme.js" defer></script>

# Step 3: Check localStorage functionality
# Open DevTools > Application > Local Storage
# Look for 'theme' key

# Step 4: Verify Tailwind config
# darkMode should be set to 'class'

# Step 5: Check dark: classes in templates
# Example: class="bg-white dark:bg-gray-900"

# Step 6: Test in incognito mode
# Rules out localStorage issues

Issue 5: Search Not Working

Symptoms:

  • Search returns no results
  • Search index not generated
  • JavaScript errors

Solution:

# Step 1: Enable search in config.toml
# build_search_index = true

# Step 2: Rebuild site
zola build

# Step 3: Check search index exists
ls public/search_index.en.json

# Step 4: Verify search implementation
# Check JavaScript console for errors

# Step 5: Test search index manually
# Visit: http://yourdomain.com/search_index.en.json

# Step 6: Check content has searchable text
# Ensure posts have content, not just front matter

Issue 6: Slow Build Times

Symptoms:

  • zola build takes too long
  • Development server slow to reload

Solution:

# Step 1: Identify bottlenecks
time zola build

# Step 2: Optimize images
# Use WebP format
# Compress images before adding

# Step 3: Reduce Tailwind CSS size
# Ensure content paths are specific in tailwind.config.js
# Remove unused plugins

# Step 4: Enable caching
# Add to netlify.toml or CI config

# Step 5: Limit search index
# Exclude large content from search

# Step 6: Profile Zola build
zola build --verbose

Issue 7: Deployment Fails

Symptoms:

  • Build succeeds locally but fails on platform
  • Deployment logs show errors
  • Site not updating after push

Solution:

# Step 1: Check deployment logs
# View full logs in Netlify/Cloudflare dashboard

# Step 2: Verify environment variables
# Check Zola version, Node version set correctly

# Step 3: Test build command locally
npm run build

# Step 4: Check for platform-specific issues
# File path case sensitivity (Mac/Linux vs production)
# Line endings (CRLF vs LF)

# Step 5: Verify netlify.toml or build config
# Ensure paths are correct
# Check publish directory set to 'public'

# Step 6: Clear build cache
# Most platforms have "Clear cache and retry" option

# Step 7: Check for large files
# Deployments may fail if repo too large
# Add large files to .gitignore

Issue 8: RSS Feed Not Updating

Symptoms:

  • RSS feed shows old content
  • Feed not generated
  • Invalid feed format

Solution:

# Step 1: Enable RSS in config.toml
# generate_feed = true

# Step 2: Check feed template exists
# Should have: templates/rss.xml (if custom)

# Step 3: Rebuild site
zola build

# Step 4: Verify feed exists
ls public/rss.xml

# Step 5: Validate RSS feed
# Use: https://validator.w3.org/feed/

# Step 6: Check feed URL in templates
# Should be: {{ get_url(path="rss.xml", trailing_slash=false) }}

# Step 7: Clear CDN cache
# If using CDN, purge cache for rss.xml

Quality Control Checklist

SOP-015: Pre-Deployment Quality Checklist

Frequency: Before every production deployment
Responsible Role: QA/Developer
Estimated Time: 20 minutes

Content Quality

General Content:

  • [ ] All page titles are descriptive and unique
  • [ ] All meta descriptions are 150-160 characters
  • [ ] No spelling or grammar errors
  • [ ] All links work (internal and external)
  • [ ] All images have alt text
  • [ ] Content is up-to-date and accurate
  • [ ] Copyright year is current

Blog Posts:

  • [ ] Post has proper front matter
  • [ ] Date is correct
  • [ ] Tags and categories assigned
  • [ ] Reading time estimated (if used)
  • [ ] Featured image set (if applicable)
  • [ ] Author attribution correct
  • [ ] Code blocks have language specified
  • [ ] Internal links use proper syntax

Technical Quality

Build & Configuration:

  • [ ] zola build completes without errors
  • [ ] npm run build:css completes successfully
  • [ ] No broken links (run zola check)
  • [ ] config.toml base_url is correct for environment
  • [ ] All static assets exist in correct directories
  • [ ] Generated files are in public/ directory

Performance:

  • [ ] Lighthouse Performance score: 95+
  • [ ] First Contentful Paint: < 1.0s
  • [ ] Largest Contentful Paint: < 2.5s
  • [ ] Cumulative Layout Shift: < 0.1
  • [ ] Total page size: < 500KB (excluding images)
  • [ ] Images optimized (WebP, compressed)
  • [ ] CSS file minified
  • [ ] HTML minified (if enabled)

Accessibility:

  • [ ] Lighthouse Accessibility score: 95+
  • [ ] Proper heading hierarchy (only one h1 per page)
  • [ ] All interactive elements keyboard accessible
  • [ ] Color contrast ratios meet WCAG AA standards
  • [ ] Forms have proper labels (if applicable)
  • [ ] Focus indicators visible
  • [ ] ARIA labels used appropriately
  • [ ] Screen reader tested (if available)

SEO:

  • [ ] Lighthouse SEO score: 95+
  • [ ] All pages have unique titles
  • [ ] All pages have meta descriptions
  • [ ] Open Graph tags present
  • [ ] Twitter Card tags present
  • [ ] Canonical URLs set correctly
  • [ ] Sitemap generated (sitemap.xml exists)
  • [ ] Robots.txt configured properly
  • [ ] RSS feed generated
  • [ ] Structured data added (if applicable)

Visual Quality

Layout & Design:

  • [ ] Layout consistent across all pages
  • [ ] Navigation works on all pages
  • [ ] Footer appears on all pages
  • [ ] No broken layouts at any screen size
  • [ ] Consistent spacing and alignment
  • [ ] Typography hierarchy clear
  • [ ] Brand colors used consistently

Responsive Design:

  • [ ] Mobile (375px): All content readable and accessible
  • [ ] Tablet (768px): Layout adjusts appropriately
  • [ ] Desktop (1920px): Content not too wide, well-centered
  • [ ] Navigation works on mobile (hamburger menu if used)
  • [ ] Images scale properly at all sizes
  • [ ] Touch targets at least 44x44px on mobile
  • [ ] No horizontal scrolling (unless intentional)

Dark Mode:

  • [ ] Dark mode toggle works
  • [ ] All text readable in dark mode
  • [ ] All images visible in dark mode
  • [ ] Proper contrast in dark mode
  • [ ] Syntax highlighting works in dark mode
  • [ ] Theme preference persists

Browser Compatibility

Desktop Browsers:

  • [ ] Chrome (latest): Full functionality
  • [ ] Firefox (latest): Full functionality
  • [ ] Safari (latest): Full functionality
  • [ ] Edge (latest): Full functionality

Mobile Browsers:

  • [ ] Safari iOS (latest): Full functionality
  • [ ] Chrome Android (latest): Full functionality

Functionality Testing

Navigation:

  • [ ] All nav links work
  • [ ] Breadcrumbs correct (if used)
  • [ ] Pagination works on blog index
  • [ ] Category/tag pages load correctly
  • [ ] 404 page displays for invalid URLs

Search:

  • [ ] Search functionality works
  • [ ] Search returns relevant results
  • [ ] Search handles no results gracefully
  • [ ] Search index up-to-date

Forms (if applicable):

  • [ ] All form fields validate correctly
  • [ ] Form submissions work
  • [ ] Error messages display properly
  • [ ] Success messages display properly

Security Checklist

Headers:

  • [ ] Security headers configured (CSP, X-Frame-Options)
  • [ ] HTTPS enforced
  • [ ] HSTS enabled
  • [ ] No mixed content warnings

Privacy:

  • [ ] Privacy policy page exists (if collecting data)
  • [ ] Cookie notice (if using cookies)
  • [ ] Analytics configured properly
  • [ ] External scripts from trusted sources only

Deployment Checklist

Pre-Deployment:

  • [ ] All changes committed to Git
  • [ ] Version number updated (if applicable)
  • [ ] Changelog updated
  • [ ] Team notified of deployment

Deployment:

  • [ ] Production build created successfully
  • [ ] Deployment completed without errors
  • [ ] DNS records correct (if domain change)
  • [ ] SSL certificate valid

Post-Deployment:

  • [ ] Homepage loads correctly
  • [ ] Sample blog post loads correctly
  • [ ] Static page loads correctly
  • [ ] Search works on production
  • [ ] RSS feed accessible
  • [ ] Sitemap accessible
  • [ ] Analytics tracking (if used)

Sign-Off

Tested by: ___________________________
Date: ___________________________
Environment: [ ] Staging [ ] Production
Status: [ ] PASS [ ] FAIL [ ] PASS WITH NOTES

Notes:

[Any issues found or notes about the deployment]

Appendix

A. Useful Commands Reference

# Zola Commands
zola init [project-name]          # Create new Zola site
zola serve                        # Start development server
zola serve --interface 0.0.0.0    # Serve on all interfaces
zola serve --port 8080            # Serve on custom port
zola build                        # Build production site
zola build --base-url [url]       # Build with custom base URL
zola check                        # Check for broken links
zola --version                    # Show Zola version

# npm Commands
npm install                       # Install dependencies
npm update                        # Update dependencies
npm outdated                      # Check for outdated packages
npm audit                         # Check for vulnerabilities
npm audit fix                     # Fix vulnerabilities
npm run dev:css                   # Build Tailwind (watch mode)
npm run build:css                 # Build Tailwind (production)
npm run dev                       # Run both dev servers
npm run build                     # Full production build

# Git Commands
git status                        # Check status
git add .                         # Stage all changes
git commit -m "message"           # Commit with message
git push origin main              # Push to main branch
git pull origin main              # Pull latest changes
git log --oneline                 # View commit history
git diff                          # View changes
git checkout -b [branch-name]     # Create new branch
git tag -a v1.0.0 -m "message"    # Create tag

# File Operations
du -sh public/                    # Check build size
ls -lh static/css/                # List CSS files with sizes
find . -name "*.md" | wc -l       # Count markdown files
grep -r "search-term" content/    # Search in content

B. File Templates

Blog Post Template:

+++
title = ""
date = 2025-10-06
description = ""
draft = true

[taxonomies]
tags = []
categories = []

[extra]
author = ""
featured_image = ""
+++

Write your content here...

Static Page Template:

+++
title = ""
description = ""
template = "page.html"
date = 2025-10-06

[extra]
show_in_nav = true
nav_order = 1
+++

Page content...

C. Resources & Links

Official Documentation:

  • Zola: https://www.getzola.org/documentation/
  • Tailwind CSS v4: https://tailwindcss.com/docs
  • Tera (Template Engine): https://keats.github.io/tera/

Tools:

  • Lighthouse: https://developers.google.com/web/tools/lighthouse
  • W3C Validator: https://validator.w3.org/
  • Image Optimization: https://squoosh.app/
  • RSS Validator: https://validator.w3.org/feed/

Communities:

  • Zola Forum: https://zola.discourse.group/
  • Tailwind Discord: https://discord.gg/tailwindcss

D. Contact & Support

Project Lead: [Name]
Email: [email]
GitHub: [repository URL]
Documentation: [wiki/docs URL]

E. Version History

Version Date Changes Author
1.0.0 2025-10-06 Initial SOP document [Author]

F. Approval

Reviewed by: ___________________________
Approved by: ___________________________
Date: ___________________________

End of Document

This SOP should be reviewed and updated quarterly or when significant changes are made to the project structure, tools, or processes.