librawssg Docs

Installation

This guide covers how to install and set up librawssg for building your own static site generator, or for integrating it into an existing Rust project.

Prerequisites

  • Rust toolchain – Install the latest stable Rust via rustup.
  • Cargo – Comes with Rust; used for building and managing dependencies.

Adding librawssg as a Dependency

librawssg is a workspace of several crates. The easiest way is to use the facade crate librawssg that re‑exports the essential components.

Add the following to your Cargo.toml:

[dependencies]
librawssg = "1.0.0"

If you are working within the same workspace as the librawssg source, use a path dependency instead: 

[dependencies]
librawssg = { path = "../librawssg" }

Feature Flags

The facade crate re‑exports librawssg_templates with the tera feature enabled by default. This gives you TeraRenderer and TeraContextBuilder. If you want to disable the Tera integration (for a custom renderer), set default-features = false: 

[dependencies]
librawssg = { version = "1.0.0", default-features = false }

Basic Project Setup

To create a minimal static site generator using librawssg, follow these steps:

  1. Create a new binary crate:

    cargo new my-site-generator
cd my-site-generator

  2. Add dependencies to Cargo.toml:

    [dependencies]
librawssg = "1.0.0"

  3. Create the necessary directories and files:

    mkdir -p content templates static

  4. Place your content, templates, and static assets in the respective folders.

  5. Write a main.rs that builds and runs the pipeline (see example below).

Minimal Example

The following example uses a simple raw HTML processor and the Tera renderer. It processes .raw files, renders them with a base template, and copies static files. 

use librawssg::{
    Config, ContentRule, Document, FileSystem, Metadata, PipelineBuilder, Processor,
    RealFs, TeraContextBuilder, TeraRenderer,
};
use std::path::{Path, PathBuf};

struct RawProcessor;

impl Processor for RawProcessor {
    fn name(&self) -> &'static str {
        "raw"
    }

    fn can_process(&self, rel: &Path, _orig: &Path) -> bool {
        rel.extension().and_then(|e| e.to_str()) == Some("raw")
    }

    fn process(
        &self,
        fs: &dyn FileSystem,
        rel: &Path,
        content_dir: &Path,
    ) -> librawssg::Result<Option<Document>> {
        let full_path = content_dir.join(rel);
        let body = fs.read_to_string(&full_path)?;
        let title = rel.file_stem().unwrap_or_default().to_string_lossy().to_string();
        let meta = Metadata::new(title, String::new())?;
        let url = rel.with_extension("html").to_string_lossy().to_string();
        let output = PathBuf::from(&url);
        let doc = Document::new(meta, body, url, output, rel.to_path_buf(), 0, "page".to_string(), false)?;
        Ok(Some(doc))
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Configure the site
    let mut config = Config::new().with_site_name("My Site");
    config.add_content_rule(ContentRule::new("page", "**/*.raw", "base.tera"));
    config.build.content_dir = "content".into();
    config.build.output_dir = "dist".into();
    config.build.static_dir = "static".into();

    // 2. Set up the renderer and load templates
    let mut renderer = TeraRenderer::new();
    renderer.load_templates_dir(Path::new("templates"))?;

    // 3. Build the pipeline
    let pipeline = PipelineBuilder::new()
        .config(config)
        .content_dir("content")
        .output_dir("dist")
        .with_fs(Box::new(RealFs))
        .with_renderer(Box::new(renderer))
        .with_context_builder(Box::new(TeraContextBuilder))
        .add_processor(Box::new(RawProcessor))
        .build()?;

    // 4. Run the generation
    pipeline.run()?;
    println!("Site generated in 'dist'");
    Ok(())
}

Building the Documentation Site Itself

The librawssg repository includes a docs crate that generates this documentation website. To build it locally: 

cargo run -p docs

The output will be written to docs/dist/. You can open index.html to view the site.

Directory Structure

A typical project using librawssg has the following layout: 

my-site-generator/
├── Cargo.toml
├── content/           # Source content files (.raw, .md, etc.)
├── templates/         # Tera templates
├── static/            # Static assets (CSS, JS, images)
└── src/
    └── main.rs        # Entry point

Next Steps