Usage Guide

Spaz is new and is under active development. Please report any bugs or great ideas via Github Issues.

Basic Usage

Command Syntax

spaz [OPTIONS]

Options:
  -i, --input <INPUT>    Input directory containing markdown files [default: .]
  -o, --output <OUTPUT>  Output directory for generated HTML files [default: dist]
  -h, --help             Print help

Simple Example

spaz --input content --output site

This takes all .md files from content/ and generates HTML files in site/.

Directory Structure

Your input directory structure becomes your URL structure:

content/
├── index.md              → /index.html
├── about.md              → /about.html
└── blog/
    ├── first-post.md     → /blog/first-post.html
    └── second-post.md    → /blog/second-post.html

Writing Content

Markdown Support

Spaz uses pulldown-cmark and supports standard CommonMark with Github-flavored extras.

Navigation

Create links between pages using standard markdown links:

# About

Learn more [here](/guide/)

[Back to Home](/)

Output Structure

After running spaz, your dist/ directory contains:

dist/
├── index.html              # Your pages as HTML
├── about/
│   └── index.html
└── blog/
    ├── index.html
    ├── first-post/
    │   └── index.html
    └── second-post/
        └── index.html

Deployment

The generated dist/ directory is fully static and can be deployed anywhere:

Netlify

# Connect your repo and set build command to:
cargo run --release -- --input docs --output dist

GitHub Pages

Push your generated dist/ folder or use GitHub Actions:

- name: Build Spaz
  run: cargo run --release -- --input docs --output dist

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: dist

Static Server

# Python
cd dist
python3 -m http.server 8000

# Node.js
cd dist
npx http-server

Tips & Tricks

Structuring Large Sites

Organize complex sites by sections:

docs/
├── index.md
├── guide.md // having this at the top-level causes it to show in the nav bar
├── guide/
│   ├── getting-started.md
│   ├── installation.md
│   └── advanced.md
├── api/
│   ├── index.md // this causes the `/api/` index page to exist, but does _not_ show in the nav bar
│   ├── overview.md
│   ├── endpoints.md
│   └── authentication.md
└── about.md

Rebuilding

Spaz is fast—rebuild your entire site instantly:

spaz --input docs --output dist

Great for CI/CD pipelines and automated builds!