al9000 Documentation

Overview

These are my notes on the static site builder that runs al9000.com. I wrote it in Rust with MiniJinja providing the horsepower (MiniJinja being the Rust version of Jinja). The implementation is based of dozens of prior iterations built over the past several years.

The overall goal is to remove as much friction as possible from making web pages. And, not just blog posts, but pages with any given structure or content. The three keys that support that are:

1. All content files are templates with the full range of MiniJinja features available for processing. Each one can output directly or be used as an include in another file.

2. A global d variable is available in each template that contains the metadata from every content file as well as the data from every .json file on the site.

3. TODO: Images don't require paths. They can be stored anywhere in the content tree and accessed with their filename alone.

Content Processing

• Every file in the content tree can be used as a template that can be processed to generate its output. This allows the use of all MiniJinja logic, filters, and functions inside each content file.

• Every file is available to be included in other templates.

• Files with .html, .js, and .txt are passed through the transformation engine by default.

• TODO: If an .html, .js, or .txt file has .off in its file name then it's copied directly without going through the transformation engine.

• Files with other extensions are copied without transformation by default.

• Files and with .inc in their names are available to be included but are not copied to the output tree.

• TODO: Neopolitan files (i.e. .neo files) pass through the Neopoligen engine then the MiniJinja engine before being sent to the output tree as .html files.

• TODO: Each file can contain an id value defined in its metadata. Other pages can use the id in link(ID) functions to automatically create a link to the page with its title and a URL that points to the page regardless of where it's moved.

Templates

• The default MiniJinja tags are converted to make them easier to read/scan:

  {% %} becomes [! !]

  {{ }} becomes [@ @]

  {# #} becomes [# #]

• MiniJinja line statements are enabled with == used as the token. For example, instead of creating a block with:

  [! block main !]
  content
  [! endblock !]
  

  I can do:

  == block main
  content
  == endblock 
  

  which is much nicer to look at.

Global Data

• All .json files are available in the global d variable inside each template. For example, give a JSON file at:

  /path/to/data.json
  

  with the content:

  { "alfa": "bravo" }
  

  Doing this:

  [@ d.path.to.data.alfa @]
  

  Outputs:

  bravo
  

• The global data can be used inside control flows inside any content file. For example:

  <ul>
    == for key in d.path.to.data
      <li>[@ key @]</li>
    == endfor
  </ul>
  

• The metadata from each page is available in the global d variable as well (see below):

Page Metadata Access

• Page metadata is stored in TMOL format.

• The metadata is stored inside a toml block. e.g.

  == block toml
  title = "page title"
  == endblock
  

  This block can be stored anywhere in the content file.

• The metadata for each page is added to the global d variable. For example, the title key from the toml metadata in the file:

  /some/content/file.html
  

  is available in:

  [@ d.some.content.file.title @]
  

• Page metadata is also available via a p variable. For example, the page title can be output with:

  [@ p.title @]
  

File Path Data

The f variable holds file path data.

• f.dir - An array with the directories that lead to the file (e.g. /path/to/something.inc.html returns ["path", "to"]. An empty array is returned if the file is at the docroot).

• f.dir_string - The string to the parent directory (including a leading /).

• f.extension - The final file extension (i.e. something.inc.html returns html). NONE is returned if there's no extension.

• TODO: f.input_extension - The input file's extension (e.g. .neo which would result in an f.extension of .html).

• TODO: f.input_path - The array with the path parts to the input file.

• TODO: f.input_path_string - The string with the path to the input file (includes the leading /).

• f.name - The full file name

• f.stem - The stem of the file name. (Note that this is everything up to the last . which means something.inc.html returns something.inc).

• f.path - An array with the output directory and file name (e.g. /path/to/something.inc.html returns ["path", "to", "something.inc.html"]. (Use f.input_path` to get the input file path with the original extension.)

• TODO: f.path_string - Returns the output path to the file as a string. It's the absolute path which includes a leading /. (Use f.input_path_string to get the source files path.)

• TESTING:

{
  "dir": [
    "docs"
  ],
  "dir_string": "/docs",
  "extension": "html",
  "name": "index.html",
  "path": [
    "docs",
    "index.html"
  ],
  "path_string": "/docs/index.html",
  "stem": "index"
}

Images

• TODO: Source images can be stored anywhere in the content tree.

• TODO: A /site-images is automatically generated to house optimized versions of images.

• TODO: Optimized versions of each image are generated in

    /site-images/CHAR1/CHAR2/BASENAME/FILENAME-WxH.EXT
  

• TODO: An img function takes the basename (i.e. without an extension) of an image and auto generates the img tag with the full proper paths. For example:

    [@ img("example-image") @]
  
  Generates images with source sets pointing to:
  
    /site-images/e/x/example-image/example-image-WxH.jpg
  

• TODO: The img function takes an optional alt argument that populates the alt text for the output img tag.

• TODO: The img function takes an optional classes argument that populates the class attribute of the output img tag.

• Create function that lets you call images with just their file basename without the extension to output the optimized image set (e.g. calling [@ img("some-img") @]would create the image tag with the path

Open Graph Images

• These are the image that show up as previews on social media sites when you post a link on them.

• The base metadata include file looks for an og-image.jpg file next to the page it's rendering. If it finds one, it uses it. Otherwise, it uses the default OG image.

• TODO: Auto-generate OG Images with page titles for text for each page. These will be called og-image-auto.jpg. The titles will update when the title of a page updates. If an og-image.jpg file exists, it will override the og-image-auto.jpg.

Filters

• code("LANGUAGE")

  • returns a syntax highlighted version of the input ready to be placed inside an inline <code class="code-span"> tag.

  • Highlighting is done by defining classes on the individual span tags

  • No additional spans are added to supports line numbers (the highlight function does that).

• highlight("LANGUAGE")

  • returns a syntax highlighted version of the input ready to be placed inside a <pre><code> block.

  • The LANGUAGE defines which language to use for the highlighting.

  • Highlighting is done by defining classes on the individual span tags

  • A span tag that can be used for placing line numbers is prepended to each line.

• highlight_block("LANGUAGE" [, CLASSES])

  • returns a syntax highlighted version of the input including a surrounding <pre class="code-block"><code> block.

  • The LANGUAGE defines which language to use for the highlighting.

  • Highlighting is done by defining classes on the individual span tags

  • A span tag that can be used for placing line numbers is prepended to each line.

• md

  • Passes the content through a markdown parser and returns the result.

  • The result is a MiniJinja safe value so no additional autoescaping is applied.

• output_block([TITLE [, CLASSES]])

  • Outputs a block of text in <div class="output-block CLASSES"><div class="title">TITLE</div> <pre><code>CONTENT tags.

Functions

• TODO: data(path)

  • Returns the json/toml data for the given path by effectively turning /some/path/file.html into j.some.path.file

• date(DATE [, FORMAT])

  • TODO: Takes an RFC 3339 date and returns a string with the date.

  • Can also take a TOML date from the frontmatter.

  • The default format is MONTH, YEAR.

  • The optional FORMAT argument can be passed for other formats (the formatting is done with standard date formatting tokens).

• exists(PATH)

  • Returns true if the given path exists.

  • Otherwise, returns false.

  • Expected paths are absolute based on the site docroot.

• TODO: filename(PATH)

  • Returns the full filename for a given path (e.g. /path/to/file.inc.html returns file.inc.html).

• files_in_folder(PATH [, ext = EXT][, full = true])

  • Takes a string that's the path to a folder.

  • Returns an array with the names of all the files inside the given path.

  • TODO: If the optional EXT arguments is passed, then only files with a matching file extension are returned.

  • TODO: If the optional full argument is passed then full paths are returned.

• TODO: folders_in_folder(PATH [, full=BOOL])

  • Takes a string that's the path to a folder.

  • Returns an array with the names of all the folders inside the given path.

  • TODO: Passing true to the optional full argument returns the full paths to the folder instead of just the name.

• TODO: link(ID [, classes=""])

  • TODO: Generates an a tag with and href that points to the URL of the file with the given ID.

  • Takes an optional classes argument. The string of the argument is added to the a tag.

• parent(PATH)

  • Takes a string that's the path to a file or directory.

  • Returns a string with the path to the parent directory.

• TODO: parts(PATH)

  • Takes a string that's the path to a file or directory.

  • Returns an array of strings where each element is a folder in the path.

• TODO: raw_include(PATH)

  • Includes the contents of the file at PATH without further processing.

• stem(PATH)

  • Takes a string that's the path to a file or folder.

  • If the path is a file, then the file stem is returned (e.g. /some/path/alfa.txt returns alfa)

  • If the path is a folder, then the folders basename is returned (i.e. parts of the names after dots don't get removed so: /some/path/bravo.inc/ returns bravo.inc)

• timestamp([DATE])

  • Returns the current timestamp in RFC 3339 format.

  • When an optional DATE argument is passed it gets parsed and used to generate the RFC 3339 timestamp. (The incoming DATE currently only supports the private TOML payload from the frontmatter.)

• uuid([STRING])

  • Returns a UUID by default.

  • If the optional STRING argument is passed the returned value is a UUID v5 (which will always return the same UUID for a given input string.)

Local Tools

• The generator has a built-in preview server.

• The preview server has hot-reload which triggers a page refresh after a rebuilt of the site.

• TODO: The preview server includes dynamic tools to aid in production of the site:

  • TODO: link-getter: takes a URL and returns a link tag whose text is pulled from the title of the remote page.

  • TODO: Built-in File Deployer let's individual files and folder be deployed without having to screw around with git. (The backend is still all git based, it's just abstracted away.

Standard Metadata

Standard page metadata tags I'm using:

• created
• id
• link_text
• status
• subtitle
• tags
• title
• updated

Flags

Flags for customizing aspects of the pages are defined via a flags key in the TOML block. Individual templates are responsible for handling behavior changes from the flags. Currently, the only flag is:

• no-date - prevent the date from displaying in the title section of a page.

• no-title - prevent the title block from showing up on the page (i.e. the hgroup element in the default page)

Others will be added as necessary.

Templates can check for flags like:

== if "no-date" not in p.flags 
Show date here since no-date is not in the flags.
== endif