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:

title             -- See site.title
baseUrl           -- See site.baseUrl
languageCode      -- See site.languageCode
defaultLayout     -- See site.defaultLayout

redirections      -- Table with source URLs as keys and target URLs are values.

ignoreFiles       -- Array of filename patterns to exclude from site generation.
ignoreFolders     -- Array of folder name patterns to exclude from site generation.

processors        -- Table with file content processors.

rewriteOutputPath -- See below.
rewriteExcludes   -- See below.

autoLockPages     -- See below.

before            -- Function that is called before site generation.
after             -- Function that is called after main site generation.
validate          -- Function that is called after all tasks are done.

htaccess          -- See below.

All fields are optional.

redirections

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

config.redirections = {
	["/old-post/"] = "/new-post/",
	["/duck/"]     = "https://duckduckgo.com/",
}

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

rewriteOutputPath

Use this to control where files are written inside the output folder. Note that URLs don't 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 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"

rewriteExcludes

This is an array of path patterns for files that should not be rewritten by rewriteOutputPath. Example:

-- Exclude topmost .htaccess file.
config.rewriteExcludes = {"^/%.htaccess$"}

autoLockPages

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

htaccess

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 file 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.
redirect -- Flag for using mod_rewrite to redirect URLs.
www      -- Flag for whether mod_rewrite should add or remove www from request URLs.

htaccess.errors

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

config.htaccess.errors = {
	[404] = "/error/404/",
	[500] = "/error/internal-server/",
}

htaccess.redirect

If set, then rewrite directives are added for all page aliases and redirections. To control where the directives are inserted, add the following to the line where they should be inserted:

# :webgen.rewriting:

htaccess.www

If false then "www." is removed if present. If true then "www." is added if missing. Uses mod_rewrite.