« ReFreezed.com
LuaWebGen

Site Configuration

Site-specific configurations are stored in config.lua in the site root. The file is expected to return a table with any of these fields:

redirections

config.redirections = table

Table of URL redirections, with source URLs as keys and target URLs as values. Example:

config.redirections = {
	["/original-post/"] = "/new-post/",           -- Internal redirect.
	["/duck/"]          = "http://duck.example/", -- External redirect.
}

Also see page.aliases for page-level redirections/aliases (which work exactly the same), and htaccess.redirect if you're on an Apache server.

redirectionLayout

config.redirectionLayout = layoutName

Set what layout should be used for .html files that redirect visitors. For example, a value of "redirect" corresponds to the file layouts/redirect.html. If this is empty then a simple default file is generated. Default: ""

Layout pages will have the page.redirectionTarget value set to the redirection target URL.

ignoreFiles

config.ignoreFiles = filenamePatterns

Array of filename patterns for files to exclude from site generation. Example:

-- Exclude Photoshop files.
config.ignoreFiles = {"%.psd$"}
See also: ignoreFolders, ignorePaths

ignoreFolders

config.ignoreFolders = filenamePatterns

Array of filename patterns for folders to exclude from site generation. Example:

config.ignoreFolders = {
	"^backup$",
	"^temp$",
}
See also: ignoreFiles, ignorePaths

ignorePaths

config.ignorePaths = pathPatterns

Array of path patterns for files to exclude from site generation. Example:

config.ignorePaths = {
	"^/images/.*%.psd$", -- Exclude all Photoshop files in the images folder (including subfolders).
	"^/work-in-progress/secret-project/", -- Exclude everything in the secret folder.
}
See also: ignoreFiles, ignoreFolders

types

config.types = table

Table of template file types, with file extensions as keys and file types as values. Valid types are "markdown", "html", "xml" and "othertemplate".

"markdown" and "html" templates are considered to be actual pages (page.isPage is true).

-- Default table:
config.types = {
	["md"]       = "markdown",
	["markdown"] = "markdown",
	["html"]     = "html",
	["htm"]      = "html",
	["xml"]      = "xml", -- For e.g. RSS feeds and sitemaps.
	["css"]      = "othertemplate",
}

If you e.g. don't want CSS files to be treated as templates you can simply omit the "css" line above.

processors

config.processors = table

Table with file content processors, with file extensions as keys and functions as values. All files pass through these functions right before being written to the output folder (including HTML files). The function should take the file contents as its first argument and return the modified (or unmodified) data. Example:

config.processors["css"] = function(cssData, sourcePath)
	print("Processing CSS file: "..sourcePath)
	cssData = cssData:gsub("/%*.-%*/", "") -- Remove comments.
	return cssData
end

dataTextParsers

config.dataTextParsers = table

v1.2 Data with text data parsers, with file extensions as keys and function as values. When data is accessed from the data folder (through the data object) the appropriate function from this table or dataBinaryParsers will be called. Functions should have this signature:

luaValue = function( textDataString, pathInCwd )

The returned value must not be nil.

Unlike dataBinaryParsers, the data strings will have normalized line endings (so they will always use newlines). It is assumed the files are ASCII compatible (like UTF-8).

Example:

-- config.lua
config.dataTextParsers = {
	keys_and_values = function(s)
		local t = {}
		for line in s:gmatch"[^\n]+" do
			local k, v = line:match"^(%S+)%s*=%s*(.*)$"
			if k then  t[k] = v  end
		end
		return t
	end,
}

-- data/dog.keys_and_values
size     = small
cuteness = 9001

-- content/dog.md
Dog cuteness is {{ data.dog.cuteness }}!

See DATA_FILE_EXTENSIONS for data formats that already have parsers.

dataBinaryParsers

config.dataBinaryParsers = table

v1.2 Data with binary data parsers, with file extensions as keys and function as values. When data is accessed from the data folder (through the data object) the appropriate function from this table or dataTextParsers will be called. Functions should have this signature:

luaValue = function( binaryDataString, pathInCwd )

The returned value must not be nil.

See DATA_FILE_EXTENSIONS for data formats that already have parsers.

rewriteOutputPath

config.rewriteOutputPath = pathFormat
rewrittenPath = config.rewriteOutputPath( path )

Use this to control where files are written inside the output folder. Note that URLs are not affected and do not change! Example usage of rewriteOutputPath is to use it together with URL rewriting on the server. Most people should ignore this configuration entirely.

If the value is a string then it's used as format for the path. Example:

config.rewriteOutputPath = "/subfolder%s" -- %s is the original path.
-- "content/index.html"   is written to "output/subfolder/index.html"
-- "content/blog/post.md" is written to "output/subfolder/blog/post/index.html"
-- etc.

If the value is a function then the function gets the original path as it's argument and is expected to return the rewritten path. Example:

config.rewriteOutputPath = function(path)
	-- Put .css and .js files in a subfolder.
	if isAny(getExtension(path), "css","js") then
		return "/subfolder"..path
	end
	return path
end

Default: "%s" (i.e. paths are not rewritten)

See also: rewriteExcludes

rewriteExcludes

config.rewriteExcludes = pathPatterns

Array of path patterns for files that should not be rewritten by rewriteOutputPath. Example:

-- Exclude all PNG images and the topmost .htaccess file.
config.rewriteExcludes = {
	"%.png$",
	"^/%.htaccess$",
}

autoLockPages

config.autoLockPages = bool

If the value is true then lock is called automatically right after the first code block on all pages (if the block is located at the very beginning of the file - otherwise, lock will not be called). Default: false.

before

config.before = function( )

Function that is called before regular site generation.

config.before = function()
	-- ...
end

after

config.after = function( )

Function that is called after regular site generation.

config.after = function()
	-- ...
end

validate

config.validate = function( )

Function that is called after all other tasks are done.

config.validate = function()
	-- Example task:
	validateUrls{
		"/old-folder/my-post/",
		"/work-in-progress/dog.png",
	}
end

htaccess

config.htaccess = table

This is a table with special Apache server .htaccess file settings. If this field is set then a .htaccess is automatically created at the top of the output folder. If the .htaccess already exists then new directives are appended to the end of the file, unless otherwise noted.

The table can have any of these fields:

errors    -- Table with HTTP error documents.
noIndexes -- Flag for disabling automatic directory listings.
redirect  -- Flag for using mod_rewrite to redirect URLs.
www       -- Flag for whether mod_rewrite should add/remove www from request URLs or not.

htaccess.errors

config.htaccess.errors = table

Table with HTTP error codes as keys and documents as values. Writes ErrorDocument directives. Example:

config.htaccess.errors = {
	[404] = "/error/404/index.html",
	[500] = "/error/internal-server/index.html",
	[403] = "Forbidden!",
	[401] = [["Unauthorized Access - incorrect login details"]],
}

Note: Pages for specified documents are automatically marked as special.

htaccess.noIndexes

config.htaccess.noIndexes = bool

If true, disables automatic directory listings. It adds this directive:

Options -Indexes

Default: false.

htaccess.redirect

config.htaccess.redirect = bool

If true then rewrite directives are added for all page aliases and redirections. To control where the directives are inserted, if you already have an .htaccess file, add the following line where they should be inserted:

# :webgen.rewriting:

If this line isn't present then the directives are added at the end of the file. Default: false.

Note: Source URLs with queries only redirect exact URL matches.

config.redirections = {
	["/?a=1&b=2"] = "/foobar/",
	-- This redirects '/?a=1&b=2' to '/foobar/'.
	-- It does not redirect '/?b=2&a=1' or '/?a=1&b=2&c=3'.
}

htaccess.www

config.htaccess.www = bool

If true then "www." is either added or removed depending on what format is used in config.baseUrl. If false then URLs are not rewritten. Uses mod_rewrite. Default: false.

Page updated: 2022-04-13