qsgen2/HOWTO.md

Quick Site Generator 2 (qsgen2) - User Guide

Table of Contents

1. Introduction
2. Installation
3. Quick Start
4. Project Structure
5. Content Creation
   • Pages
   • Blog Posts
6. Markup Languages
   • QSTags
   • Markdown
   • Conversion Between Formats
7. Themes and Templates
8. Configuration
9. Command Reference
10. Advanced Usage
11. Troubleshooting
12. Contributing

Introduction

Quick Site Generator 2 (qsgen2) is a powerful static site generator written in Zsh. It's designed to be fast, flexible, and easy to use, with support for both custom QSTags and standard Markdown syntax.

Installation

1. Clone the repository:

   git clone https://github.com/kekePower/qsgen2.git
   cd qsgen2
   

2. Make the script executable:

   chmod +x qsgen2
   

3. Add to your PATH (optional):

   echo 'export PATH="$PATH:'$(pwd)'"' >> ~/.zshrc
   source ~/.zshrc
   

Quick Start

1. Create a new site:

   ./qsgen2 new my-site
   cd my-site
   

2. Build the site:

   ./qsgen2 build
   

3. Preview the site:

   ./qsgen2 serve
   

Project Structure

my-site/
├── config             # Site configuration
├── content/           # Source content
│   ├── pages/         # Static pages
│   └── blog/          # Blog posts
├── themes/            # Site themes
├── static/            # Static files (images, CSS, JS)
└── output/            # Generated site (created on build)

Content Creation

Pages

Create a new page:

./qsgen2 new page about

Pages use the .qst extension and can include QSTags or Markdown.

Blog Posts

Create a new blog post:

./qsgen2 new post my-first-post

Blog posts use the .blog extension and support the same markup as pages.

Markup Languages

QSTags

QSTags is a simple markup language used by qsgen2. Example:

#H1 Welcome to My Site#EH1
#P This is a paragraph with #BDbold#EBD and #Iitalic#EI text.#EP

Markdown

Markdown is also supported:

# Welcome to My Site

This is a paragraph with **bold** and *italic* text.

Conversion Between Formats

Convert a single file to Markdown:

./qsgen2 convert --to-markdown content/pages/about.qst content/pages/about.md

Convert all files to Markdown:

./qsgen2 convert --to-markdown --all

Convert back to QSTags:

./qsgen2 convert --to-qstags --all

Themes and Templates

Themes are stored in the themes directory. Each theme can include:

• Page templates
• Blog post templates
• CSS/JavaScript
• Assets

Configuration

Edit config/site.conf to customize your site:

site_name = "My Awesome Site"
site_url = "https://example.com"
site_author = "Your Name"
theme = "default"

Command Reference

Build Commands

• build: Build the site
• clean: Remove generated files
• serve: Start a local server

Content Management

• new page <name>: Create a new page
• new post <title>: Create a new blog post
• convert: Convert between markup formats

Utility Commands

• version: Show version information
• help: Show help message

Advanced Usage

Custom Build Scripts

Create a build.zsh file in your project root:

#!/usr/bin/env zsh
# Custom build script

# Clean previous build
./qsgen2 clean

# Convert all content to Markdown for editing
./qsgen2 convert --to-markdown --all

# Build the site
./qsgen2 build

# Optimize images
find output -name "*.jpg" -exec jpegoptim --strip-all {} \;

Troubleshooting

Common Issues

1. Permission Denied

   chmod +x qsgen2
   

2. Command Not Found Add qsgen2 to your PATH or use ./qsgen2

3. Build Errors Check for syntax errors in your content files

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - See LICENSE for details.

---

Quick Site Generator 2 - A fast, flexible static site generator