Configuration

Directory Structure

Spaz expects your documentation to be organized in markdown files:

docs/
├── index.md
├── about.md
├── getting-started/
│   ├── install.md
│   └── config.md
└── usage.md

Each markdown file becomes a page in your SPA. Nested directories create nested routes.

File Naming

• File names become route segments (e.g., about.md → /about/)
• Hyphens in filenames are preserved in routes (e.g., getting-started.md → /getting-started/)
• The index.md file becomes the root page (/)

Front Matter

Pages support optional YAML front-matter to configure metadata and site-wide settings. Front-matter must be at the beginning of your markdown file, delimited by ---:

---
title: Page Title
date: 2024-01-15
sort_order: 1
---

# Your content here

Page-Level Metadata

These can be used in any markdown file:

• title (string): Override the auto-generated page title
• date (string): Publication date for sorting pages chronologically
• sort_order (number): Explicit ordering for pages (lower numbers first)

Site-Wide Configuration (index.md only)

These special fields can only be used in /index.md to configure the entire site:

• logo_url (string): URL to a logo image to display in the header
• logo_replaces_home (boolean): When true and a logo is set, hides the “Home” text link from navigation (the logo still links to home)
• nav_links (array): Extra links to display in the top navigation bar

Example index.md

---
title: My Project
logo_url: /static/images/logo.png
logo_replaces_home: true
nav_links:
  - label: GitHub
    url: https://github.com/username/project
  - label: Twitter
    url: https://twitter.com/username
---

# Welcome

Your site content here...

Running the Generator

Basic usage:

spaz --input docs --output dist

This will:

1. Read all .md files from the docs directory
2. Generate corresponding HTML files in the dist directory
3. Create styles.css and spa-routing.js

Output Structure

The generator creates the following structure:

dist/
├── index.html
├── about/
│   └── index.html
├── getting-started/
│   ├── install/
│   │   └── index.html
│   └── config/
│       └── index.html
├── styles.css
└── spa-routing.js

Each page includes the full navigation bar and sidebar (if applicable).