Usage Guide

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 extras:

# Headings

All heading levels work: H1, H2, H3, etc.

## Links

[Link text](/page.html)
[External link](https://example.com)

## Code Blocks

\`\`\`rust
fn main() {
    println!("Hello, Spaz!");
}
\`\`\`

## Lists

- Unordered lists
- With multiple items

1. Ordered lists
2. Work too

## Emphasis

**Bold**, *italic*, and `inline code` all work.

## Block Quotes

> This is a quote
>
> With multiple lines

Create links between pages using standard markdown links:

# About

Learn more [here](/guide.html)

[Back to Home](/index.html)

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/
│   ├── getting-started.md
│   ├── installation.md
│   └── advanced.md
├── api/
│   ├── overview.md
│   ├── endpoints.md
│   └── authentication.md
└── about.md

Index Pages

Create index.md files in directories for section landing pages:

docs/
├── blog/
│   ├── index.md           → /blog/index.html (blog overview)
│   ├── post-1.md          → /blog/post-1.html
│   └── post-2.md          → /blog/post-2.html

Linking Best Practices

Always use .html in links for the generated site:

[Link to page](/path/to/page.html)

Rebuilding

Spaz is fast—rebuild your entire site instantly:

spaz --input docs --output dist

Great for CI/CD pipelines and automated builds!

Next Steps