Lib.rs

› Web programming | Template engine
#static-site-generator #lua-script #lua #website #website-generator #static-website #javascript

app slsg

Scriptable Lua Site Generator

Owned by Dimev.

1 unstable release

0.1.0 Apr 13, 2024

#556 in Template engine

GPL-3.0-only

670KB
2K SLoC

Rust 1.5K SLoC // 0.1% comments Lua 487 SLoC // 0.2% comments

SLSG

Scriptable Lua Site Generator

How does this differ from other site generators?

  • lssg uses lua as it's scripting and templating language, allowing for more complex logic with less boilerplate for generating sites
  • lssg allows pages to be made from lua, thus allowing to generate a different file structure than the defined one in the file system

How to use it

lssg new [name] to initialize a new project. This will create a directory with that name, a site.toml file, the content directory, style, static and lib directory

lssg init initializes the current directory as a new site, if it's empty

site/ is for the site, lib/ is for lua scripts, styles/ is for sass stylesheets, static/ is for statically accessible files

The completed website is output to public/, or the folder specified by -o or --output

lssg build builds the site by looking at the first found site.toml file in the current or any ancestor directories.

lssg cookbook [name] shows a script that may be useful when making a site. Run without name to see the full list.

How to use:

lssg runs the site/index.lua file, which is expected to return a page this page is then converted into a website

The final returned item of this script is expected to be a page

index.lua, as well as all other scripts found in site/ or subdirectories get access to a global named script. This serves as the main way to interact with the file system They also get access to the config table, which is loaded from site.toml

script:

  • colocated: directory for the colocated files, if this was an index.lua file, otherwise an empty directory
  • name: stem of the *.lua file, or directory name if index.lua
  • static: directory for the static files
  • styles: return table of files, for the style

directory:

  • files: table for all colocated files
  • directories: table for all colocated directories
  • scripts: table for all colocated scripts (*.lua, or ./index.lua)

file:

  • can be created with the site.file(text) function
  • parseMd(): parses the file as markdown
  • parseJson(): parses the file as json, into a table
  • parseYaml(): parses the file as yaml, into a table
  • parseToml(): parses the file as toml, into a table
  • parseTxt(): loads the file as a string
  • parseBibtex(): loads the file as bibtex, into a table
  • stem: file stem if any, or nil
  • name: file name if any, or nil
  • extention: file extention if any, or nil

markdown:

  • front(): the front matter as a table, or nil if none. --- is parsed as yaml, +++ is parsed as toml
  • raw: the raw markdown text
  • html(flow): the markdown as html, accepts a bool for whether to allow mdx flow, as in text between {} to be interpreted specially
  • ast(flow): the markdown as the ast (table), accepts a bool for whether to allow mdx flow, as in text between {} to be interpreted specially See the cookbook page on markdown for more details on how to use this

page:

  • can be created with the page(name) function
  • withFile(path, file): adds a file at the given relative path
  • withHtml(html): adds html to the page. If no html is used, no index.html file is generated for the directory
  • withPage(page): adds a subpage to the page

Other globals

  • warn: Accepts a single string, warnings will be shown in the terminal and error page

lssg library

  • site.debug: bool, true if the site is built from the serve command
  • escapeHtml: escapes the given html string

Rendering HTML

Besides including these page and file searching functions, there's also a small library for rendering html This is available under the h table, as well as with the fragment and rawHtml functions h contains all elements as functions, with the sub() method allowing child nodes to be added, one per argument, and attrs() accepting a table of the attributes to set on the element

renderHtml() will render the given nodes to a string of html render() will do the same, but exclude the initial "<!DOCTYPE html>"

Code highlighting

TODO

Static content

Static content under the static/ folder is not included by default, and has to be added manually via withFile on page

Styling

all content under the styles folder is interpreted as css, scss or sass, depending on the extention all top-level at the root of the directory is available under the styles

Minification

all html passed in via withHtml is minified, as well as all stylesheets under style/ the minifyhtml, minifycss and minifyjs functions can be used to minify html, css and javascript respectively TODO

Config

the site.toml file can be used for configuring. everything under the [config] section is loaded into the config global

Known bugs:

  • Syntax highlighting currently leaks memory if a prefix string is given, due to the lifetime of syntects's ClassStyle::SpacedPrefixed needing to be static

Current TODO:

  • rename to SLSG
  • figure out a way to do spacing between strings nicely
  • have example site also serve as short intro to lssg (and make logo)
  • code highlighting rules for common language set
  • image resizing
  • minification(?)
  • finish docs
  • atom/rss

Cookbook TODO:

  • manual markdown rendering FINISH
  • markdown based blog (loads md)
  • atom
  • search index?
  • bibtex bibliography

Dependencies

~12–23MB
~351K SLoC