Home - ReFreezed/LuaWebGen GitHub Wiki

Note: The documentation has moved to the LuaWebGen website. Information here may be out of date!

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

• Terminology
• Folder Structure
• Build Process
• Notes

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

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.

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

The index.html or 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 .json, .lua, .toml and .xml files. (See the data object for more info.)

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.

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

(Also see the scripts object.)

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:

^[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:

1. Non-templates (images, JavaScript files, etc.).
2. Non-page templates (CSS and XML files).
3. 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.

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!