trinja 0.7.1 - Docs.rs

//! # Trinja – HTML templating and Static Site Generator for RDF(S) resources
//!
//! Trinja is a library for converting arbitrary [RDF](https://www.w3.org/TR/rdf11-primer/)
//! data into HTML and also provides a *Static Site Generator* for building entire
//! web sites from RDF. It relies on [minijinja](https://docs.rs/minijinja/latest/minijinja/)
//! for templating and on the [Taganak SDK](https://sdk.taganak.net/) for RDF graph handling.
//!
//! ## Linking templates to RDF(S) resources
//!
//! Trinja loosely expects its input RDF data to follow [RDF Schema](https://www.w3.org/TR/rdf-schema/),
//! as it discovers HTML templates from the RDF types of resources. Consider the following RDF data:
//!
//! ```turtle
//! @prefix ex: <https://sdk.taganak.net/vocab/examples/> .
//!
//! <#leonardo> a ex:Turtle ;
//!   ex:name "Leonardo" ;
//!   ex:image "https://static.wikia.nocookie.net/tmnt/images/8/8b/Leonardo.png" .
//!
//! <#raphael> a ex:Turtle ;
//!   ex:name "Raphael" ;
//!   ex:image "https://static.wikia.nocookie.net/tmnt/images/5/5a/Raphael.png" .
//! ```
//!
//! Linking a minijinja template to these resources can be done in several ways:
//!
//! ```turtle
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//! @prefix ex: <https://sdk.taganak.net/vocab/examples/> .
//!
//! # Linking directly to one resource
//! <#leonardo> trinja:template """
//!   <img
//!     src="{{ this["<https://sdk.taganak.net/vocab/examples/image>"] }}"
//!     alt="{{ this["<https://sdk.taganak.net/vocab/examples/name>"] }}"
//!   />
//! """^^trinja:minijinja .
//!
//! # Linking directly to the RDF(S) type
//! ex:Turtle trinja:genericTemplate """
//!   <img
//!     src="{{ this["<https://sdk.taganak.net/vocab/examples/image>"] }}"
//!     alt="{{ this["<https://sdk.taganak.net/vocab/examples/name>"] }}"
//!   />
//! """^^trinja:minijinja .
//! ```
//!
//! For more alternatives and detailed documentation, see the
//! [crate docs](https://docs.rs/trinja/latest/trinja/).
//!
//! ## Defining static websites
//!
//! ### Data model
//!
//! Static websites can be defined using Trinja's custom vocabulary. While sites
//! can consist of arbitrary linked data under arbitrary IRIs, designing an IRI
//! scheme that maps nicely to the resulting website significantly simplifies the
//! model.
//!
//! #### Site
//!
//! The `Site` class is the root of a static website. It defines global attributes
//! and the other parts of the website.
//!
//! ```turtle
//! @prefix dc: <http://purl.org/dc/elements/1.1/> .
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//!
//! <> a trinja:Site ;
//!   dc:title "My website" ;
//!   trinja:template <#template> .
//! ```
//!
//! The `trinja:template` predicate points to a re-usable template that will be both
//! the default template for all pages that don't define their own template, and be
//! available under the special name `site` in template to extend.
//!
//! #### Template
//!
//! A `Template` resource defines a re-usable template. Templates can be referred to
//! by their IRI in other templates, e.g. using minijinja's `extend` or `import`
//! statements.
//!
//! ```turtle
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//!
//! <#template> a trinja:Template ;
//!   trinja:template """
//!     <!DOCTYPE html>
//!     <html>
//!       <head>
//!         <title>{% block title %}{{ site["<http://purl.org/dc/elements/1.1/title>"] }}{% endblock %}</title>
//!       </head>
//!     </html>
//! """^^trinja:minijinja .
//! ```
//!
//! Note how the `site` variable is used to reference the resource defining the `Site`.
//!
//! #### Page
//!
//! A `Page` is a single page that will result in the generation of one HTML file.
//!
//! ```turtle
//! @prefix dc: <http://purl.org/dc/elements/1.1/> .
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//!
//! <example> a trinja:Page ;
//!   dc:title "Example page" ;
//!   trinja:template """
//!     {% extends "default" %}
//!     {% block title %}{{ this["<http://purl.org/dc/elements/1.1/title>"] }}{% block title %}
//!   """^^trinja:minijinja .
//! ```
//!
//! Note how the `this` variable is used to refer to the currently rendered resource,
//! just like in simple HTML fragments described above.
//!
//! Pages can be added to a `Site` using the `trinja:page` predicate. If the predicate
//! is omitted, then all `trinja:Page` resources on the graph will be included.
//!
//! #### Asset
//!
//! Just like pages, assets will be added to the vuilt static site, but they are not
//! built using templates, but instead copied from outside the graph.
//!
//! ```turtle
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//!
//! <assets/bulma.min.css> a trinja:Asset ;
//!   trinja:source <https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css> .
//! ```
//!
//! When building the site, [Bulma CSS](https://bulma.io/) will be downloaded and
//! added to the output directory.
//!
//! To use assets in templates, the `rdf_asset` function is available. It resolves
//! an IRI on the input graph into a relative URL in the output directory:
//!
//! ```turtle
//! @prefix trinja: <https://trinja.taganak.net/vocab/> .
//!
//! <some/path/to/a/page> a trinja:Page ;
//!   trinja:template """
//!     <link rel="{{ rdf_asset("<../../../bulma>") }}" />
//!   """^^trinja:minijinja .
//!
//! <bulma> a trinja:Asset ;
//!   trinja:source <https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css> ;
//!   trinja:output "style/bulma.min.css".
//! ```
//!
//! This template will correctly insert a relative link to the output CSS file.
//! Note that the `../../../` in the `rdf_asset` IRI reference does not reflect
//! the relative location in the output directory, but on the input graph.w
//!
//! ### Example site
//!
//! An example site is available in the
//! [respository's example/ directory](https://codeberg.org/Taganak/trinja/src/branch/main/example).
//!
//! ## Library usage
//!
//! <div class="warning">
//!
//! Using trinja as a library in other code is not yet officially supported.
//!
//! </div>
//!
//! ## Command line usage
//!
//! The `trinja` command can be used to render individual RDF resources as HTML
//! fragments or to build entire static websites from linked data.
//!
//! All commands access a single RDF source as a graph. To facilitate working with
//! local directories, especially when using Trinja as SSG, the default graph uses
//! the custom `file+glob` graph source provided by Taganak, using the pattern
//! `**/*.ttl` starting from the current directory.
//!
//! ### Rendering single resources
//!
//! ```shell
//! $ trinja -q "file://$PWD/example.ttl" resource "file://$PWD/example.ttl#leonardo" render
//! <img
//!   src="https://static.wikia.nocookie.net/tmnt/images/8/8b/Leonardo.png"
//!   alt="Leonardo"
//! />
//! ```
//!
//! ### Building static sites
//!
//! ```shell
//! $ cargo install trinja
//! $ trinja site build
//! 2025-06-17T19:47:50.904719Z  INFO trinja: Using default source IRI file+glob:///home/nik/Taganak/trinja/example/**/*.ttl
//! 2025-06-17T19:47:50.917814Z  INFO trinja: Using default site base IRI file:///home/nik/Taganak/trinja/example/
//! 2025-06-17T19:47:50.918969Z  INFO trinja::site: Building site, starting from file:///home/nik/Taganak/trinja/example/, to /home/nik/Taganak/trinja/example/output
//! 2025-06-17T19:47:50.919035Z  WARN trinja::site: Assets not defined on site; searching all trinja:Asset on graph
//! 2025-06-17T19:47:50.919929Z  INFO trinja::site: Storing asset from https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css into /home/nik/Taganak/trinja/example/output/style/bulma.min.css
//! 2025-06-17T19:47:51.265031Z  INFO trinja::site: Storing asset from https://static.wikia.nocookie.net/tmnt/images/9/94/Michelangelo.png into /home/nik/Taganak/trinja/example/output/michelangelo.png
//! 2025-06-17T19:47:51.506999Z  INFO trinja::site: Storing asset from https://static.wikia.nocookie.net/tmnt/images/8/8b/Leonardo.png into /home/nik/Taganak/trinja/example/output/leonardo.png
//! 2025-06-17T19:47:51.855151Z  INFO trinja::site: Storing asset from https://static.wikia.nocookie.net/tmnt/images/5/5a/Raphael.png into /home/nik/Taganak/trinja/example/output/raphael.png
//! 2025-06-17T19:47:52.093873Z  INFO trinja::site: Storing asset from https://static.wikia.nocookie.net/tmnt/images/e/e7/Donatello.png into /home/nik/Taganak/trinja/example/output/donatello.png
//! 2025-06-17T19:47:52.369318Z  WARN trinja::site: Pages not defined on site; searching all trinja:Page on graph
//! 2025-06-17T19:47:52.370115Z  INFO trinja::site: Rendering page <file:///home/nik/Taganak/trinja/example/turtles> into /home/nik/Taganak/trinja/example/output/turtles.html
//! 2025-06-17T19:47:52.380577Z  INFO trinja::site: Rendering page <file:///home/nik/Taganak/trinja/example/#frontpage> into /home/nik/Taganak/trinja/example/output/index.html
//!
//! $ tree ./output/
//! ./output/
//! ├── donatello.png
//! ├── index.html
//! ├── leonardo.png
//! ├── michelangelo.png
//! ├── raphael.png
//! ├── style
//! │   └── bulma.min.css
//! └── turtles.html
//! ```
//!
//! Note how the assets have been placed in the desired output locations
//! (and correctly been linked in the HTML output).
//!
//! ## Current limitations
//!
//! Trinja is in very early development. The following limitations hence apply:
//!
//! * API and vocabulary are unstable and will undergo changes before the first stable
//!   release
//! * Relative paths generated for assets and page links are not sanitized (do not
//!   handle untrusted source graphs)
//! * Most template errors will currently panic without a useful error message

mod env;
pub mod res;
pub mod site;

use std::sync::{Arc, RwLock};

use language_tags::LanguageTag;
use minijinja::Environment;
use taganak_orm::re::{BasicPrefixMap, GraphError, Term};
use thiserror::Error;

pub struct WithEnv;
pub struct WithBase;

/// Error cases for Trinja's operations
#[derive(Debug, Error)]
pub enum Error {
    /// Error accessing output directories and files
    #[error("IO error")]
    IO(#[from] std::io::Error),
    /// Error accessing the source graph
    #[error("Graph error")]
    GraphError(#[from] GraphError),
}

#[derive(Debug)]
struct ParamsWithEnv<'a, G> {
    base: Option<Arc<Term>>,
    graph: Arc<RwLock<G>>,
    prefix_map: Arc<BasicPrefixMap>,
    language: Option<LanguageTag>,
    environment: Arc<RwLock<Environment<'a>>>,
}

impl<G> Clone for ParamsWithEnv<'_, G> {
    fn clone(&self) -> Self {
        ParamsWithEnv {
            base: self.base.clone(),
            graph: self.graph.clone(),
            prefix_map: self.prefix_map.clone(),
            language: self.language.clone(),
            environment: self.environment.clone(),
        }
    }
}

impl<'a, G> ParamsWithEnv<'a, G> {
    fn base(mut self, base: Option<Arc<Term>>) -> Self {
        self.base = base;
        self
    }

    fn graph<G2>(self, graph: Arc<RwLock<G2>>) -> ParamsWithEnv<'a, G2> {
        let Self {
            base: term,
            graph: _,
            prefix_map,
            language,
            environment,
        } = self;

        ParamsWithEnv {
            base: term,
            graph,
            prefix_map,
            language,
            environment,
        }
    }

    fn prefix_map(mut self, prefix_map: Arc<BasicPrefixMap>) -> Self {
        self.prefix_map = prefix_map;
        self
    }

    fn language(mut self, language: Option<LanguageTag>) -> Self {
        self.language = language;
        self
    }

    fn environment(self, environment: Arc<RwLock<Environment<'_>>>) -> ParamsWithEnv<'_, G> {
        let Self {
            base,
            graph,
            prefix_map,
            language,
            environment: _,
        } = self;

        ParamsWithEnv {
            base,
            graph,
            prefix_map,
            language,
            environment,
        }
    }

    fn to_params(self) -> Params<'a, G> {
        let Self {
            base,
            graph,
            prefix_map,
            language,
            environment,
        } = self;

        Params {
            base,
            graph,
            prefix_map,
            language,
            environment: Some(environment),
        }
    }
}

#[derive(Debug)]
pub struct Params<'a, G> {
    pub base: Option<Arc<Term>>,
    pub graph: Arc<RwLock<G>>,
    pub prefix_map: Arc<BasicPrefixMap>,
    pub language: Option<LanguageTag>,
    pub environment: Option<Arc<RwLock<Environment<'a>>>>,
}

impl<G> Clone for Params<'_, G> {
    fn clone(&self) -> Self {
        Params {
            base: self.base.clone(),
            graph: self.graph.clone(),
            prefix_map: self.prefix_map.clone(),
            language: self.language.clone(),
            environment: self.environment.clone(),
        }
    }
}

impl<'a, G> Params<'a, G> {
    pub fn base(mut self, base: Option<Arc<Term>>) -> Self {
        self.base = base;
        self
    }

    pub fn graph<G2>(self, graph: Arc<RwLock<G2>>) -> Params<'a, G2> {
        let Self {
            base,
            graph: _,
            prefix_map,
            language,
            environment,
        } = self;

        Params {
            base,
            graph,
            prefix_map,
            language,
            environment,
        }
    }

    pub fn prefix_map(mut self, prefix_map: Arc<BasicPrefixMap>) -> Self {
        self.prefix_map = prefix_map;
        self
    }

    pub fn language(mut self, language: Option<LanguageTag>) -> Self {
        self.language = language;
        self
    }

    pub fn environment(self, environment: Option<Arc<RwLock<Environment<'_>>>>) -> Params<'_, G> {
        let Self {
            base,
            graph,
            prefix_map,
            language,
            environment: _,
        } = self;

        Params {
            base,
            graph,
            prefix_map,
            language,
            environment,
        }
    }

    fn to_with_env(self) -> Option<ParamsWithEnv<'a, G>> {
        let Self {
            base: term,
            graph,
            prefix_map,
            language,
            environment,
        } = self;

        Some(ParamsWithEnv {
            base: term,
            graph,
            prefix_map,
            language,
            environment: environment?,
        })
    }
}