lustre/ssg

Types

BuildError

This type represents possible errors that can occur when building the site.

pub type BuildError {
  CannotCreateTempDirectory(reason: simplifile.FileError)
  CannotWriteStaticAsset(
    reason: simplifile.FileError,
    path: String,
  )
  CannotGenerateRoute(reason: simplifile.FileError, path: String)
  CannotWriteToOutputDir(reason: simplifile.FileError)
  CannotCleanupTempDir(reason: simplifile.FileError)
}

Constructors

```
CannotCreateTempDirectory(reason: simplifile.FileError)
```
An error that can occur when trying to create a temporary directory to work in: when generating a static site, lustre_ssg first writes all the files in a temporary directory. After the generation is over, all the contents of the temporary directory are copied over to the actual output directory.
```
CannotWriteStaticAsset(
  reason: simplifile.FileError,
  path: String,
)
```
An error that can occur when trying to write a static asset to a given path.
```
CannotGenerateRoute(reason: simplifile.FileError, path: String)
```
An error that can occur when trying to generate a route at a given path.
```
CannotWriteToOutputDir(reason: simplifile.FileError)
```
An error that can occur when the building step is over and all generated documents are moved from the temporary directory to the actual output directory.
```
CannotCleanupTempDir(reason: simplifile.FileError)
```
An error that can occur when trying to delete the temporary directory.

Config

opaque </>

The Config type tells lustre_ssg how to generate your site. It includes things like the output directory and any routes you have configured.

The type parameters are used to track different facts about the configuration and prevent silly things from happening like building a site with no guaranteed routes.

If you’re looking at the generated documentation on hex.pm, these type parameters might be unhelpfully labelled “a”, “b”, “c”, etc. Here’s a look at what these type parameters are called in the source code:

pub opaque type Config(
  has_static_routes,
  has_static_dir,
  use_index_routes
)

has_static_routes indicates whether or not the configuration has at least one static route and so is guarnateed to generate at least one HTML file. It will be either HasStaticRoutes or NoStaticRoutes.

You need to add at least one static route before you can build your site using build. This is to prevent you from providing empty dynamic routes and accidentally building nothing.
has_static_dir indicates whether or not the configuration has a static assets directory to copy. It will be either HasStaticDir or NoStaticDir.

The build function will run regardless, but you may choose to wrap this function yourself to provider stricter compile-time guarantees if you want to ensure that your static assets are always configured.
use_index_routes indicates whether or not the configuration will generate HTML files that correspond directly to the route provided or if an index.html file will be generated at the route provided. It will be either UseDirectRoutes or UseIndexRoutes.

As with has_static_dir, the build function will run regardless, but you may use this parameter for stricter compile-time guarantees.

pub opaque type Config(
  has_static_routes,
  has_static_dir,
  use_index_routes,
)

HasStaticDir

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that has a static assets directory to copy.

pub type HasStaticDir

HasStaticRoutes

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that will generate least one static route.

pub type HasStaticRoutes

NoStaticDir

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that does not have a statica ssets directory to copy.

pub type NoStaticDir

NoStaticRoutes

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that will not generate any static routes.

Your configuration must have at least one static route before it can be passed to build. This is to prevent you from accidentally building a completely empty site.

pub type NoStaticRoutes

UseDirectRoutes

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that will generate HTML files that correspond directly to the route provided, for example the route “/blog” will generate a file at “/blog.html”.

pub type UseDirectRoutes

UseIndexRoutes

</>

This type is used to tag the Config through the different builder functions. It indicates a configuration that will generate an index.html file at the route provided, for example the route “/blog” will generate a file at “/blog/index.html”.

pub type UseIndexRoutes

Functions

add_dynamic_route

</>

pub fn add_dynamic_route(
  config: Config(a, b, c),
  path: String,
  data: Dict(String, d),
  page: fn(d) -> Element(e),
) -> Config(a, b, c)

Configure a map of dynamic routes to be generated. As with add_static_route the base path should be the route that each page will be available at when served by a HTTP server.

The initial path is the base for all dynamic routes to be generated. The keys of the data map will be used to generate the dynamic routes. For example, to generate dynamic routes for a blog where each page is a post with the route “/blog/:post” you might do:

let posts = [
  #("hello-world", Post(...)),
  #("why-lustre-is-great", Post(...)),
]

...

ssg.config("./dist")
|> ...
|> ssg.add_dynamic_route("/blog", posts, render_post)

Paths are converted to kebab-case and lowercased. This means that the path “/Blog” will be available at “/blog” and and “/About me” will be available at “/about-me”.

add_static_asset

</>

pub fn add_static_asset(
  config: Config(a, b, c),
  path: String,
  content: String,
) -> Config(a, b, c)

Include a static asset in the generated site. This might be something you want to be generated at build time, like a robots.txt, a sitemap.xml, or an RSS feed.

The path should be the path that the asset will be available at when served by an HTTP server. For example, the path “/robots.txt” would be available at “https://your_site.com/robots.txt”. The path will be converted to kebab-case and lowercased.

If you have configured a static assets directory to be copied over, any static asset added here will overwrite any file with the same path.

add_static_dir

</>

pub fn add_static_dir(
  config: Config(a, NoStaticDir, b),
  path: String,
) -> Config(a, HasStaticDir, b)

add_static_route

</>

pub fn add_static_route(
  config: Config(a, b, c),
  path: String,
  page: Element(d),
) -> Config(HasStaticRoutes, b, c)

Configure a static route to be generated. The path should be the route that the page will be available at when served by a HTTP server. For example the path “/blog” would be available at “https://your_site.com/blog”.

You need to add at least one static route before you can build your site. This is to prevent you from providing empty dynamic routes and accidentally building nothing.

Paths are converted to kebab-case and lowercased. This means that the path “/Blog” will be available at “/blog” and and “/About me” will be available at “/about-me”.

add_static_xml

</>

pub fn add_static_xml(
  config: Config(a, b, c),
  path: String,
  page: Element(d),
) -> Config(a, b, c)

build

</>

pub fn build(
  config: Config(HasStaticRoutes, a, b),
) -> Result(Nil, BuildError)

Generate the static site. This will delete the output directory if it already exists and then generate all of the routes configured. If a static assets directory has been configured, its contents will be recursively copied into the output directory before any routes are generated.

new

</>

pub fn new(
  out_dir: String,
) -> Config(NoStaticRoutes, NoStaticDir, UseDirectRoutes)

Initialise a new configuration for the static site generator. If you pass a relative path it will be resolved relative to the current working directory, not the directory of the Gleam file.

use_index_routes

</>

pub fn use_index_routes(
  config: Config(a, b, c),
) -> Config(a, b, UseIndexRoutes)

Configure the static site generator to generate an index.html file at any static route provided. For example, the route “/blog” will generate a file at “/blog/index.html”.