Crate polysite

Highly customizable, polymorphic static site generator library, polysite.

This crate is inspired by Hakyll written in Haskell.

Concept

The concept of polysite is a set of components that can be used for static site generation. You can make your own static site generator by combining the various parts in polysite. polysite uses Metadata to store the result of each step of the compilation. Each step is passed a Context, modifies metadata, and returns a CompileResult, which represents the result of that step of the compilation task. Each step of compilation process is implemented by implementing Compiler::next_step. You can create a large compiler by piping together multiple compilers.

How to use

If you would like to simply build site written in Markdown, use compiler::markdown::MarkdownCompiler. The example is in examples/simple_markdown.rs.

How to create compiler

If you would like to create a new compiler, implement Compiler trait for your type. Compiler::next_step method is used to define each step of the compilation task.

compile! macro is provided for ease of creating pinned and boxed Future.

If you would like to pipe some compilers, use pipe! macro.

Compiler trait is implemented for closures that take a Context as an argument and return a CompilerReturn.

Metadata

polysite uses Metadata to save compilation result and it can be used in other compilation task.

There are some default metadata:

• _rule: Compiling rule name
• _version: Compiling file version
• _source: source file path
• _target: target file path
• _path: absolute URL path
• _body: Content body. For the result of each compilation task.

You can use these default key of Metadata to create new compiler.

Example

Practical example is here. Other examples are in repository.

use polysite::{
    compiler::{
        file::CopyCompiler, markdown::MarkdownCompiler, metadata::SetMetadata,
        template::TemplateEngine,
    },
    *,
};
use tracing_subscriber::prelude::*;

#[tokio::main]
async fn main() {
    let subscriber =
        tracing_subscriber::Registry::default().with(tracing_error::ErrorLayer::default());
    tracing::subscriber::set_global_default(subscriber).unwrap();

    simple_logger::SimpleLogger::new().env().init().unwrap();

    let template_engine = TemplateEngine::new("templates/**").unwrap();
    Builder::new(Config::default())
        .add_step([Rule::new(
            "metadata",
            SetMetadata::new()
                .global("site_title", "Hello, polysite!")
                .unwrap()
                .global("site_url", "https://example.com")
                .unwrap(),
        )
        .set_create(["metadata"])])
        .add_step([Rule::new(
            "posts",
            MarkdownCompiler::new(template_engine.clone(), "practical.html", None),
        )
        .set_globs(["posts/**/*.md"])])
        .add_step([
            Rule::new(
                "markdown",
                MarkdownCompiler::new(template_engine.clone(), "practical.html", None),
            )
            .set_globs(["**/*.md"]),
            Rule::new("others", CopyCompiler::new()).set_globs(["**/*"]),
        ])
        .build()
        .await
        .unwrap();
}

Modules

builder

compiler

config

error

Macros

compile

compile! macro may used to make pinned, boxed Future, which is async block.

pipe

pipe! macro may used to make large compiler from piping multiple compilers

Structs

Builder

A site builder to use build one site

Config

Context

Context holds Metadata and Config. The context is passed to Compiler::next_step, and the modified context is returned.

Metadata

Metadata holds global and local metadata, which is represented as a Value.

Rule

The Rule is used to define the rule name, source files, Version, and the Compiler used for building. The results of the compilation are saved in the Metadata, using the rule’s name as the key.

Version

Version represents the compilation file version. Once a source file has been built, any subsequent builds of the same source path with the same version will be skipped.

Enums

CompileStep

Error

Traits

Compiler

All compiler must implement Compiler trait.

Type Aliases

CompileResult

CompileResult is the result type that returned by compiler’s compile method.

CompilerReturn

CompilerReturn is boxed Future, which executes compile.