Frequently Asked Questions

General Questions

What is Spaz?

Spaz is a static site generator that converts markdown files into a fast, interactive SPA (Single Page Application) with client-side routing powered by JavaScript.

Why should I use Spaz instead of Jekyll, Hugo, or Next.js?

• Simpler than Hugo/Jekyll: No templates or configuration needed
• Faster than Next.js: Pure static HTML, no server required
• Cleaner than Gatsby: No GraphQL, no complex plugin system
• Best for: Documentation, blogs, marketing sites, knowledge bases

Spaz excels when you want simplicity and speed without build complexity.

Is Spaz production-ready?

Yes! It generates fully static HTML that can be deployed anywhere. JavaScript routing is embedded in every page, guaranteeing consistent client-side navigation across all deployments.

Technical Questions

What markdown features are supported?

Spaz supports CommonMark with extras including:

• Headings (H1-H6)
• Lists (ordered and unordered)
• Code blocks (with syntax highlighting support via HTML)
• Links and images
• Block quotes
• Tables (via pulldown-cmark extras)
• Emphasis (bold, italic)
• And all standard CommonMark features

Check the Usage Guide for examples.

Can I use custom CSS/JavaScript?

Not directly through Spaz’s generator. Instead:

1. Static directory: Copy a static/ folder to your dist manually
2. Post-process: Add CSS/JS after Spaz generates HTML
3. Modify templates: Edit src/main.rs to customize the HTML template

How do I add custom styling?

Edit the CSS in the HTML template in src/main.rs:

<style>
    body {{ font-family: ...; }}
    /* Add your CSS here */
</style>

Then rebuild.

Can I use Spaz for dynamic content?

No, Spaz is for static sites. For dynamic content, consider:

• Adding a separate API + frontend framework
• Using a traditional SSG with a CMS
• Rebuilding the site when content changes (CI/CD integration)

How do I deploy my Spaz site?

Your dist/ folder is fully static. Deploy to:

• Netlify: Automatic builds from git
• GitHub Pages: Push dist or use GitHub Actions
• Vercel: Static hosting
• Any web host: FTP/SFTP your dist folder
• Docker: Serve dist with nginx/Apache

Usage Questions

How do I organize large sites?

Use nested directories:

docs/
├── index.md
├── guide/
│   ├── index.md              # /guide/
│   ├── getting-started.md    # /guide/getting-started.html
│   └── advanced.md           # /guide/advanced.html
├── api/
│   ├── index.md              # /api/
│   └── endpoints.md          # /api/endpoints.html

How do I create navigation menus?

Currently, you manually create links in your markdown. Example nav pattern:

In index.md:

# Home
[Guide](/guide/index.html) | [API](/api/index.html) | [About](/about.html)

(See ticket s-0eba for auto-generated navigation)

Can I use relative links?

It’s best to use absolute paths from the site root:

[Good](/page.html)           ✓ Works everywhere
[Risky](../page.html)        ✗ Fragile with nested pages

How do I build in CI/CD?

Example GitHub Actions workflow:

name: Build Spaz

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - run: cargo run --release -- --input docs --output dist
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist

How do I handle redirects?

Spaz doesn’t have built-in redirect support. For redirects:

1. HTML meta redirects: Create an HTML file with meta redirect
2. Server redirects: Configure your web server (nginx, Apache)
3. Keep old URLs: Maintain old paths and let them stay

Can I have .html files in my input directory?

Spaz only processes .md files. If you need HTML files:

1. Keep them in a separate folder and copy after build
2. Convert them to markdown
3. Edit the source code to support HTML

Performance Questions

How fast is Spaz?

• Build time: Milliseconds to seconds depending on site size
• Page load: Instant (static HTML)
• Navigation: 1-2ms with cached content
• Prefetching: Invisible to user (happens on hover)

For a site with 100 pages, builds complete in under a second.

Does Spaz minify/optimize output?

Currently, Spaz generates human-readable HTML. Optimizations you can add:

• Post-process with tools like html-minifier
• Use Brotli compression on your server
• Serve via CDN for global distribution

How large can my site be?

Spaz has no practical limits. Sites with thousands of pages build in seconds. The limiting factor is your hardware, not Spaz.

Troubleshooting

My site doesn’t navigate properly

Check that:

1. Links use correct paths: /about/ for directory-based routing
2. Links use absolute paths: /page/ not page/
3. Check browser console for any JavaScript errors
4. Verify you’re not using .html extensions (the generator creates /path/index.html not /path.html)

My markdown isn’t rendering correctly

• Check that your markdown is valid CommonMark
• Verify the file is in the input directory
• Check for .md extension (case-sensitive on Linux)
• See Usage Guide for supported syntax

Site works locally but not after deploy

Usually a path issue:

1. Check your hosting root path—is it / or /spaz/?
2. Verify all links use absolute paths from site root
3. Check server is serving static files correctly

Support

If you can’t find an answer:

1. Check the Architecture page for technical details
2. Review the Usage Guide for examples
3. Report issues on GitHub

Next Steps

• Usage Guide - Full usage reference
• Architecture - Technical deep dive