Welcome to the documentation for LuaWebGen. See the sidebar for all topics.
Here are some words and phrases used throughout the documentation.
|Base URL||This is the part of the URL that everything on your website will exist under, e.g.
|Homepage||The homepage, or front page, is the index page at the top of the website and in the content folder.|
|Index page||This is any
|Layout||A layout is a
|Markdown||This is a markup language that can be used as a more light-weight alternative to HTML for pages. By default, these files use
|Page||A page is, by default, a
|Permalink||A permalink, or permanent link, is simply the absolute URL to a page or other resource.|
|Template||A template is, by default, a
|Webpage||A webpage is a
LuaWebGen expects this folder structure for a website project:
new site command creates a good starting
point for a new website.
webgen new site "my-website"
Everything in the content folder will be processed and end up in the output folder.
The file and folder structure inside this folder represents where things will be in the built website.
For example, the file
content/blog/post.md will be processed and written to
output/blog/post/index.html and get the URL
index.md file is the homepage for the website.
It's probably a good idea to have one of these.
This folder acts like a database, or a repository containing global values.
It can contain
data object for more info.)
This is the default layout template used for pages.
This folder contains build log files. A new file is written each time the website is built. These include everything that's been printed.
When building the website, this is where all processed files end up. These are the files that should be uploaded to your server.
This folder contains
.lua files defining global functions.
If you try to call
foo() from your code then
scripts/foo.lua will load.
(Files can be in subfolders, so calling e.g.
abc.xyz() will load
Script files must return a function.
(Also see the
config.lua file contains site-specific information, like the website's title and base URL.
It can also define functions to be called at different points during the build process
(e.g. before or after the processing of content files).
This is the sequence of steps performed by the program when building a website:
|3.||Process files in content folder.||template|
|5.||Write redirection files.||template|
|8.||Clean up output folder.||-|
 The context determines what actions can be performed by your code in that step (i.e. which context-specific functions can be called).
 Files in the content folder will be processed in this order:
- Non-page templates (CSS and XML files).
- Pages (HTML and Markdown files).
Note that a non-page template may trigger generation of pages prematurely (e.g. by calling
Pages will be generated in two steps: first the content of the page (from the file in the content folder), then the layout (which will insert the result from the first step into itself). It's possible for a page to say no layout should be used, in which case there's only one step. Templates that aren't pages (CSS and XML files) use no layout and thus also only have one step.
You can use any standard Lua library normally in your code, like
You cannot add you own globals directly - use the scripts folder to define global functions, and the data folder to store globally accessible data. The idea is that this restriction should prevent accidental global access.
Important: The output folder is automatically cleaned from files and folders that do not exist in the content folder, so don't save any files in the output folder!
Page updated: 2021-07-07