lustre_ssg - v0.8.3

lustre/ssg/djot

Types

Renderer

</>

A renderer for a djot document knows how to turn each block or inline element into some custom view. That view could be anything, but it’s typically a Lustre element.

Some ideas for other renderers include:

  • A renderer that turns a djot document into a JSON object
  • A renderer that generates a table of contents
  • A renderer that generates Nakai elements instead of Lustre ones

Sometimes a custom renderer might need access to the TOML metadata of a document. For that, take a look at the render_with_metadata function.

This renderer is compatible with v1.0.1 of the jot package.

pub type Renderer(view) {
  Renderer(
    codeblock: fn(Dict(String, String), Option(String), String) ->
      view,
    emphasis: fn(List(view)) -> view,
    heading: fn(Dict(String, String), Int, List(view)) -> view,
    link: fn(jot.Destination, Dict(String, String), List(view)) ->
      view,
    paragraph: fn(Dict(String, String), List(view)) -> view,
    strong: fn(List(view)) -> view,
    text: fn(String) -> view,
    code: fn(String) -> view,
    image: fn(jot.Destination, String) -> view,
    linebreak: fn() -> view,
  )
}

Constructors 

  • Renderer(
  codeblock: fn(Dict(String, String), Option(String), String) ->
    view,
  emphasis: fn(List(view)) -> view,
  heading: fn(Dict(String, String), Int, List(view)) -> view,
  link: fn(jot.Destination, Dict(String, String), List(view)) ->
    view,
  paragraph: fn(Dict(String, String), List(view)) -> view,
  strong: fn(List(view)) -> view,
  text: fn(String) -> view,
  code: fn(String) -> view,
  image: fn(jot.Destination, String) -> view,
  linebreak: fn() -> view,
)

Functions

content

</> 
pub fn content(document: String) -> String

Extract the djot content from a document with optional frontmatter. If the document does not have frontmatter, this acts as an identity function.

default_renderer

</> 
pub fn default_renderer() -> Renderer(Element(a))

The default renderer generates some sensible Lustre elements from a djot document. You can use this if you need a quick drop-in renderer for some markup in a Lustre project.

frontmatter

</> 
pub fn frontmatter(document: String) -> Result(String, Nil)

Extract the frontmatter string from a djot document. Frontmatter is anything between two lines of three dashes, like this:

---
title = "My Document"
---

# My Document

...

The document must start with exactly three dashes and a newline for there to be any frontmatter. If there is no frontmatter, this function returns Error(Nil),

metadata

</> 
pub fn metadata(
  document: String,
) -> Result(Dict(String, Toml), ParseError)

Extract the TOML metadata from a djot document. This takes the frontmatter and parses it as TOML. If there is no frontmatter, this function returns an empty dictionary.

If the frontmatter is invalid TOML, this function returns a TOML parse error.

render

</> 
pub fn render(document: String, renderer: Renderer(a)) -> List(a)

Render a djot document using the given renderer. If the document contains frontmatter it is stripped out before rendering.

render_with_metadata

</> 
pub fn render_with_metadata(
  document: String,
  renderer: fn(Dict(String, Toml)) -> Renderer(a),
) -> Result(List(a), ParseError)

Render a djot document using the given renderer. TOML metadata is extracted from the document’s frontmatter and passed to the renderer. If the frontmatter is invalid TOML this function will return the TOML parse error, but if there is no frontmatter to parse this function will succeed and just pass an empty dictionary to the renderer.

✨ Search Document