luassg

Static site generator written with Lua

Screenshots

Two Implementations Available

luassg comes with two implementations:

1. Monolithic Version (

luassg.lua

)

A single-file implementation that processes everything in one process.

2. Pipeline Version (6 separate Lua files)

A modular pipeline implementation with parallel processing capabilities.

Pipeline Architecture

The pipeline version splits the generation process into discrete stages with two operating modes:

Sequential Pipeline Mode:

luassg_launcher.lua → luassg_scanner.lua → luassg_reader.lua → luassg_substitution.lua → luassg_writer.lua

Parallel Processing Mode:

luassg_launcher.lua → luassg_scanner.lua → (Multiple luassg_process_file.lua instances in parallel)

Pipeline Components:

1. luassg_launcher.lua
   - Orchestrator
   • Loads templates and constants
   • Initializes the pipeline
   • Measures total execution time

2. luassg_scanner.lua
   - Directory Scanner (with parallel processing)
   • Scans
     ./data/
     for entity directories
   • Matches entities with available templates
   • Launches processes in parallel batches
   • Monitors and manages background processes

3. luassg_reader.lua
   - XML Reader
   • Reads individual XML files
   • Parses entity data (fields and attributes)
   • Extracts entity IDs and content

4. luassg_substitution.lua
   - Template Processor
   • Replaces placeholders in templates
   • First replaces constants (
     __CONST.NAME__
     )
   • Then replaces entity values (
     {entity.field}
     )

5. luassg_writer.lua
   - File Writer
   • Writes final HTML to
     ./output/
     directory
   • Names files as
     entity-id.html
   • Handles file creation and error reporting

6. luassg_process_file.lua
   - Complete Pipeline for Single File
   • Combines reader, substitution, and writer stages
   • Processes one XML file completely
   • Used for parallel processing mode

Templates

Templates are HTML files stored in the

Template Example:

./templates/gallery.html

Template Placeholders:

• Entity fields:
  {entity_name.field_name}
  (e.g.,
  {gallery.title}
  )
• Constants:
  __CONST.CONSTANT_NAME__
  (e.g.,
  __CONST.SITENAME__
  )

Content (XML Data Files)

XML data files define the content for each page and are stored in entity-specific directories within

XML Example:

./data/gallery/gallery-37158403-3cfe-4922-92e2-46326f0eb571.xml

XML Structure:

• Root tag: Must match the entity name (
  gallery
  in this example)
• id
  attribute: Unique identifier for the entity
• Child elements: Each becomes a field accessible via
  {entity_name.field_name}

Constants

Global constants are defined in

Constants Example:

./data/CONST.xml

Using Constants in Templates:

Parallel Processing Features

The scanner supports parallel batch processing:

Key Features:

• Configurable batch size - Process multiple files simultaneously
• Process monitoring - Tracks all background processes
• Clean completion - Waits for all processes before exiting
• Timeout handling - Prevents hanging processes
• Output management - No stray output in terminal

Configuration:

Modify the

Inter-Process Communication

The pipeline uses file-based communication between stages:

• Each stage reads input from a temporary file
• Processes the data
• Writes output to another temporary file for the next stage
• Temporary files are cleaned up after use

For parallel processing, each

• Receives parameters via command line
• Uses shared constants file
• Writes output directly to
  ./output/
  directory
• Logs progress to individual log files

Benefits of Pipeline Approach

• Modularity: Each component can be tested independently
• Scalability: Parallel processing of multiple files
• Maintainability: Smaller, focused code files
• Robustness: Isolated failures don't crash the entire system
• Monitorability: Each stage logs its progress and timing
• Performance: Significant speedup with parallel processing

Performance Comparison

Note: Actual speedup depends on CPU cores, disk I/O, and file sizes.

File Structure

./
├── luassg.lua                    # Monolithic version
├── luassg_launcher.lua           # Pipeline orchestrator
├── luassg_scanner.lua            # Directory scanner (with parallel processing)
├── luassg_reader.lua             # XML file reader
├── luassg_substitution.lua       # Template processor
├── luassg_writer.lua             # HTML file writer
├── luassg_process_file.lua       # Complete pipeline for single file
├── data/
│   ├── CONST.xml                 # Global constants
│   ├── gallery/                  # Gallery entities
│   │   └── gallery-37158403-3cfe-4922-92e2-46326f0eb571.xml
│   ├── page/                     # Page entities
│   ├── product/                  # Product entities
│   └── longread/                 # Article entities
├── templates/
│   ├── gallery.html              # Gallery template
│   ├── page.html                 # Page template
│   ├── product.html              # Product template
│   └── longread.html             # Article template
└── output/                       # Generated HTML files

Output Example

For the gallery example above, running luassg generates:

Generated File:

Usage

For Monolithic Version:

For Pipeline Version:

Helper Commands:

Advanced Usage: Custom Batch Size

For large sites, adjust the parallel processing batch size:

Processing Order

1. Constants from
   ./data/CONST.xml
   are loaded first
2. For each template, constants (
   __CONST.NAME__
   ) are replaced
3. Then entity-specific values (
   {entity.field}
   ) are replaced
4. Generated HTML files are saved to
   ./output/
   directory

Error Handling

Both versions include error handling for:

• Missing templates or directories
• Malformed XML files
• Missing constants
• File permission issues
• Process timeout in parallel mode
• Background process failures

Monitoring Parallel Processing

When using parallel processing, the scanner provides detailed feedback:

• Shows PIDs of all background processes
• Monitors process completion
• Displays batch progress
• Lists all generated files
• Handles cleanup of temporary files

GUI

GUI XML CRUD Application - A graphical interface for managing your XML content files.

Pagination Feature

luassg now includes a powerful pagination system for organizing content into category pages, generating index pages, and creating sitemaps.

Overview

The pagination feature (

• Groups entities by category
• Generates paginated category pages
• Creates a main index page
• Builds both HTML and XML sitemaps
• Supports category inclusion/exclusion

File Structure

./
├── luassg_pagination.lua          # Pagination generator
├── data/
│   ├── pagination.xml             # Pagination configuration
│   └── ... (other XML data files)
├── templates/
│   └── pagination/
│       ├── categoryTemplate.html  # Template for category pages
│       ├── indexTemplate.html     # Template for index page (optional)
│       └── sitemapTemplate.html   # Template for HTML sitemap
└── output/
    └── ... (generated pagination files)

Configuration File:

pagination.xml

Create

Configuration Options:

Category Template

Create

Category Template Placeholders:

Sitemap Template

Create

Generated Files

The pagination generator creates:

1. Category Pages

./output/category-{category}-page-{page}.html

Example:

2. Index Page

./output/index.html

Main site index using content from the

3. Sitemaps

./output/sitemap.html          # Human-readable HTML sitemap
./sitemap.xml                  # XML sitemap for search engines

XML Sitemap Format

The XML sitemap follows the sitemaps.org protocol:

Usage

Run the pagination generator:

Output Example:

luassg_pagination - Generating paginated lists and sitemap...
=============================================================
Parsing pagination settings from ./data/pagination.xml...
Loading constants from ./data/CONST.xml...
Loaded 3 constants
Checking templates...
  Found category template: ./templates/pagination/categoryTemplate.html
  Found sitemap template: ./templates/pagination/sitemapTemplate.html

Collecting entity data from XML files...
Found 14 entities in XML files
Grouping entities by category...
Found 7 categories
  - quotes: 1 entities
  - product: 2 entities
  - gallery: 1 entities
  - longread: 2 entities
  - page: 2 entities
  - posts: 3 entities
  - news: 3 entities

Generating category pages...
  Processing category: quotes (1 entities)
    Generated: category-quotes-page-1.html
  Processing category: product (2 entities)
    Generated: category-product-page-1.html
  ...

Generating index page...
  Generated index page: ./output/index.html

Generating sitemap...
  Generated sitemap: ./output/sitemap.html
  Generated XML sitemap: ./sitemap.xml

============================================================
PAGINATION GENERATION COMPLETED
============================================================
Total time: 18.47 ms
Total entities processed: 14
Total categories: 7
Total category pages generated: 6

Integration with Main Pipeline

The pagination feature works independently but complements the main luassg pipeline:

1. First: Run the main generator to create individual entity pages

2. Then: Run the pagination generator to create category lists

Customizing Entity Display

In the category template, the

Performance

The pagination generator is optimized for speed:

• Processes all entities in a single pass
• Uses efficient XML parsing
• Generates minimal file I/O operations
• Typically completes in under 20ms for 50+ entities

Benefits

• Automatic organization: Groups content by category
• SEO-friendly: Creates XML sitemaps for search engines
• Navigation: Built-in pagination controls
• Flexible: Configurable inclusion/exclusion lists
• Fast: Minimal overhead, parallel-ready design

Troubleshooting

If categories aren't appearing:

1. Check that the category name matches the folder name in
   ./data/
2. Verify the category is listed in the
   <include>
   section of
   pagination.xml
3. Ensure there are XML files in the category directory

If templates aren't found:

1. Create the
   ./templates/pagination/
   directory
2. Ensure
   categoryTemplate.html
   and
   sitemapTemplate.html
   exist
3. Check file permissions

Example Workflow

The pagination feature extends luassg into a complete static site solution with proper content organization and search engine optimization.

Lua Fragment Processing Feature

Overview

The Static Site Generator now supports dynamic Lua code execution within templates using

How It Works

1. Pattern: Find all occurrences of
   [lua]some lua code[/lua]
   in the template
2. Execution: Each Lua fragment is written to a temporary file and executed
3. Substitution: The fragment is replaced with the stdout output of the Lua code
4. Cleanup: Temporary files are immediately removed after execution

Example Usage

Basic Template with Lua Code:

Corresponding XML Data:

Generated Output:

Advanced Examples

1. Conditional Content

2. Loops and Iteration

3. Mathematical Calculations

4. File Operations (Reading External Data)

5. Date Manipulation

Error Handling

If a Lua fragment contains an error, it will be replaced with an error message in the output:

Performance Considerations

• Each Lua fragment executes in its own process
• Fragments are processed sequentially within each file
• Complex operations should be kept minimal for performance
• Consider caching results for expensive operations

Security Notes

• Lua fragments execute with the same permissions as the generator
• Avoid using user-provided content in Lua fragments
• Consider sanitizing inputs when using data from XML files
• Temporary files are created with unique names and deleted immediately

Integration with Existing Features

Lua fragments work seamlessly with:

• Constants:
  __CONST.SITE_NAME__
  can be used inside Lua code
• Entity Fields:
  {blog.title}
  values are already substituted before Lua execution
• Attributes:
  {blog.id}
  is available in Lua context after substitution

This feature adds powerful dynamic capabilities to your static site while maintaining the benefits of pre-rendered HTML.

Author

Nazarov A.A., Russia, Orenburg, 2026

License

Open source - free to use and modify