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)
• baseUrl (required, see site)
• languageCode (see site)
• defaultLayout (see site)
• redirections
• ignoreFiles
• ignoreFolders
• types
• processors
• rewriteOutputPath
• rewriteExcludes
• autoLockPages
• before
• after
• validate
• htaccess

---

redirections

Table of URL redirections, with source URLs as keys and target URLs as 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.

ignoreFiles

Array of filename patterns to exclude from site generation.

ignoreFolders

Array of folder name patterns to exclude from site generation.

types

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

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

-- Default table:
config.types = {
	["md"]   = "markdown",
	["html"] = "html",
	["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

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

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

before

Function that is called before site generation.

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

after

Function that is called after main site generation.

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

validate

Function that is called after all tasks are done.

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

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

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

Note: Specified document pages are automatically marked as special.

htaccess.noIndexes

This flag disables automatic directory listings. It adds this directive:

Options -Indexes

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 set then "www." is either added or removed depending on what format is used in config.baseUrl. Uses mod_rewrite.