Site Configuration - ReFreezed/LuaWebGen GitHub Wiki

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

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:

• title (see site)
• description (see site)
• baseUrl (required, see site)
• languageCode (see site)
• defaultLayout (see site)
• redirections
• redirectionLayout
• ignoreFiles
• ignoreFolders
• ignorePaths
• types
• processors
• dataTextParsers
• dataBinaryParsers
• rewriteOutputPath
• rewriteExcludes
• autoLockPages
• before
• after
• validate
• htaccess

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.

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 (the default) then a simple default file is generated.

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

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

-- Exclude Photoshop files.
config.ignoreFiles = {"%.psd$"}

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

config.ignoreFolders = {
	"^backup$",
	"^temp$",
}

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

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.

Table with file content processors, with file extensions as keys and functions as values. All files pass through these before being written to the output folder. Example:

config.processors["css"] = function(css)
	css = css:gsub("/%*.-%*/", "") -- Remove comments.
	return css
end

[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 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. Also see dataBinaryParsers().

[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 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. Also see dataTextParsers().

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

The default value for rewriteOutputPath is "%s" (i.e. paths are not rewritten).

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$",
}

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

Function that is called before regular site generation.

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

Function that is called after regular site generation.

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

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

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 or remove www from request URLs.

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.

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

Options -Indexes

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.

If true then "www." is either added or removed depending on what format is used in config.baseUrl. Uses mod_rewrite.