Configuration

librawssg uses a single configuration file to control the entire build process. This file can be written in YAML or JSON format and contains site settings, directory locations, content processing rules, and custom extra data.

Configuration File Format

The configuration can be stored as config.yaml, config.yml, or config.json. By default, the PipelineBuilder supports reading YAML via its load_config() method. For JSON, you can manually call Config::from_json_str().

# config.yaml
site:
  site_name: "My Documentation"
  description: "A site built with librawssg"
  language: "en"
  base_url: "https://example.com"
  author: "Your Name"
  repo_url: "https://github.com/username/repo"
  license: "MIT"

build:
  content_dir: "content"
  output_dir: "dist"
  templates_dir: "templates"
  static_dir: "static"

content_rules:
  - name: "page"
    pattern: "**/*.raw"
    template: "base.tera"
    list_enabled: false

Configuration Sections

site

Contains site metadata and navigation structures. All fields except site_name are optional and have sensible defaults.

NavItem Structure

Each NavItem has the following fields:

{
  "label": "Home",
  "url": "/",
  "children": []
}

• label – Display text for the link.
• url – URL the link points to (relative or absolute).
• children – Optional nested sub-items for hierarchical menus.

build

Specifies the directory locations used during the build.

content_rules

A list of rules that map file patterns to templates. Each rule has the following fields:

Example with List Generation

content_rules:
  - name: "blog"
    pattern: "blog/**/*.md"
    template: "post.tera"
    list_template: "blog_list.tera"
    list_enabled: true

extra

A free-form object for storing custom top-level data. This data can be accessed from templates via the context.

Validation Rules

The configuration is validated when the pipeline is built. The following checks are performed:

• site.site_name must not be empty or contain only whitespace.
• At least one content rule must be defined.
• Content rule names must be unique.
• Each content rule must have non-empty name, pattern, and template.
• The pattern must not contain ".." (to prevent path traversal).
• If site.base_url is set, it must begin with http:// or https://.

If any validation fails, an error of type Error::Validation is returned with a descriptive message.

Loading Configuration

From YAML

use librawssg_compiler::PipelineBuilder;

let pipeline = PipelineBuilder::new()
    .load_config("config.yaml")?
    // ... other builder methods
    .build()?;

From JSON

use librawssg_config::Config;

let json_str = r#"{
    "site": {
        "site_name": "My Site"
    },
    "build": {},
    "content_rules": [
        {
            "name": "page",
            "pattern": "**/*.html",
            "template": "base.tera"
        }
    ]
}"#;

let config = Config::from_json_str(json_str)?;

Programmatic Construction

use librawssg_config::{Config, ContentRule};

let mut config = Config::new()
    .with_site_name("My Site");

config.add_content_rule(
    ContentRule::new("page", "**/*.raw", "base.tera")
);

Serialization

The Config struct supports serialization to YAML and JSON:

let yaml = config.to_yaml_string()?;
let json = config.to_json_string()?;

This allows saving the configuration back to a file for later use.

Common Patterns

Multiple Content Types

content_rules:
  - name: "page"
    pattern: "**/*.raw"
    template: "base.tera"
  - name: "blog"
    pattern: "blog/**/*.md"
    template: "post.tera"
    list_enabled: true
    list_template: "blog_list.tera"

Custom Navigation

site:
  navbar:
    - label: "Home"
      url: "/"
    - label: "API"
      url: "/api/index.html"
      children:
        - label: "Compiler"
          url: "/api/compiler.html"
        - label: "Config"
          url: "/api/config.html"
  sidebar:
    - label: "Getting Started"
      url: "/"
    - label: "Installation"
      url: "/installation.html"

Custom Extra Data

site:
  extra:
    analytics_id: "UA-123456-7"
    social:
      twitter: "handle"

This extra data is accessible in templates via {{ site.extra }}.

Tips

• Use YAML for better readability; JSON is also fully supported.
• Keep content_rules ordered from most specific to least specific, as later rules take precedence.
• The build section can be omitted entirely; defaults will be used.
• Remember to set list_enabled: true and provide a list_template if you want index pages for a content type.