Documentation

Welcome to the documentation for LuaWebGen. See the sidebar for all topics.

Terminology
Folder Structure
Build Process
Notes

Terminology

Here are some words and phrases used throughout the documentation.

Term	Desciption
Base URL	This is the part of the URL that everything on your website will exist under, e.g. `http://www.example.com/`.
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 `index.html` or `index.md` file in the content folder. They often contain links to underlying pages.
Layout	A layout is a `.html` template that's supposed to insert the HTML content of a page into itself, or just represents any part of a webpage that isn't the content.
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 `.md` as file extension.
Page	A page is, by default, a `.html` or `.md` file in the content folder.
Permalink	A permalink, or permanent link, is simply the absolute URL to a page or other resource.
Template	A template is, by default, a `.html`, `.md`, `.xml` or `.css` file that can have embedded Lua code. All pages are templates, but not all templates are pages (e.g. CSS files). These files exist in the content and layout folders.
Webpage	A webpage is a `.html` file in the output folder.

Folder Structure

LuaWebGen expects this folder structure for a website project:

my-website/             -- Root of the website project.
    content/            -- All website content, including pages, RSS feeds, images, CSS and JavaScript files.
        index.(html|md) -- Homepage.
    data/               -- Optional data folder. Can contain Lua, TOML, JSON and XML files.
    layouts/            -- All HTML layout templates.
        page.html       -- Default page layout template.
    logs/               -- Automatically created log file folder.
    output/             -- Automatically created output folder.
    scripts/            -- Optional Lua script folder. Scripts must return a function.
    config.lua          -- Site-wide configurations.

Running the 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.

content

This folder contains all website content, including pages, RSS feeds, images, CSS and JavaScript files. 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 http://www.example.com/blog/post/.

content/index.html

The index.html or index.md file is the homepage for the website. It's probably a good idea to have one of these.

data

This folder acts like a database, or a repository containing global values. It can contain .json, .lua, .toml and .xml files. (See the data object for more info.)

layouts

This folder contains templates in the form of .html files that comprise all parts of webpages except for the content itself. Each page can specify what layout they should use.

layouts/page.html

This is the default layout template used for pages.

logs

This folder contains build log files. A new file is written each time the website is built. These include everything that's been printed.

output

When building the website, this is where all processed files end up. These are the files that should be uploaded to your server.

scripts

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 scripts/abc/xyz.lua.) Script files must return a function.

(Also see the scripts object.)

config.lua

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).

Build Process

This is the sequence of steps performed by the program when building a website:

	Operation	Context^[1]
1.	Load file `config.lua`.	none
2.	Call `config.before`.	config
3.	Process files in content folder.^[2]	template
4.	Call `config.after`.	config
5.	Write redirection files.	template
6.	(Apache) Write `.htaccess` file.	-
7.	Call `config.validate`.	validation
8.	Clean up output folder.	-

^[1] The context determines what actions can be performed by your code in that step (i.e. which context-specific functions can be called).

^[2] Files in the content folder will be processed in this order:

Non-templates (images, JavaScript files, etc.).
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 subpages).

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.

Notes

You can use any standard Lua library normally in your code, like io and os (including lfs).

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: 2022-04-13