Quarto Site Build Workflow

This repository supports both local and CI-based building of Quarto pages for GitLab Pages deployment.

Quick Start

Option 1: Local Build (Recommended)

Install prerequisites:

# Install Quarto
# Visit: https://quarto.org/docs/get-started/

# Install uv (faster Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

Build the site locally:
```
./build.sh
```

Commit and push:

# To commit pre-built site (faster CI)
git add public/
git commit -m "Update site with pre-built pages"
git push

# Or just push source changes (CI will build)
git add .
git commit -m "Update content"
git push

Option 2: CI Build Only

Simply commit your changes and push. GitLab CI will build the site automatically.

How It Works

Local Build Process

The build.sh script: 1. Checks for Quarto and uv installation 2. Installs Python dependencies using uv 3. Renders the Quarto site 4. Moves _site to public directory 5. Compresses files for better performance

CI Build Process

GitLab CI checks for a public directory: - If public exists: Uses pre-built pages (fast deployment) - If public doesn’t exist: Builds from source (slower but reliable)

File Management

_site/ - Quarto’s default output directory (ignored by git)
public/ - GitLab Pages directory (ignored by git by default)
.gitignore - Configured to ignore build artifacts

Workflow Options

Development Workflow

# Make content changes
vim some-post.qmd

# Build and preview locally
./build.sh
python -m http.server 8000 --directory public

# Commit changes (without pre-built site)
git add some-post.qmd
git commit -m "Add new post"
git push

Production Workflow

# Make content changes
vim some-post.qmd

# Build locally and test
./build.sh
python -m http.server 8000 --directory public

# Commit with pre-built site for faster deployment
git add some-post.qmd public/
git commit -m "Add new post with pre-built site"
git push

Emergency Deployment

# Force CI build (useful if local build fails)
rm -rf public/
git add .
git commit -m "Force CI build"
git push

Benefits

Local Build Benefits

Faster CI: No need to install Quarto, Python, Node.js in CI
Better debugging: Test builds locally before committing
Reduced CI costs: Less resource usage
Offline development: Build without internet connection

CI Build Benefits

Consistent environment: Same build environment every time
No local setup: Works for contributors without local Quarto installation
Automatic compression: Built-in gzip and brotli compression

Troubleshooting

Local Build Issues

# Check Quarto installation
quarto --version

# Check uv installation
uv --version

# Clean and rebuild
rm -rf _site public .venv
./build.sh

CI Build Issues

Check GitLab CI logs for specific error messages
Ensure all dependencies are listed in requirements.txt
Verify Quarto configuration in _quarto.yml

Configuration Files

build.sh - Local build script
.gitlab-ci.yml - CI configuration
_quarto.yml - Quarto site configuration
requirements.txt - Python dependencies
.gitignore - Git ignore rules

Tips

Use local builds for development - Faster iteration
Commit pre-built sites for releases - Faster deployment
Use CI builds for testing - Ensures compatibility
Monitor CI logs - Catch issues early
Keep dependencies updated - Regular maintenance