Configuration

config.toml is a a file which contains a configuration of Stag. It is written in TOML file format.

All configured options are available in templates and macros through {{ site.config }} variable.

Example Configuration

title = "My Site"
url = "https://example.com"
language = "en"

[user]
latest_pages = 6
important_pages = 6

[template]
name = "themes/blog"

[plugins.macros]
path = "macros"

[plugins.markdown]
extensions = ["footnotes", "fenced_code", "smarty", "codehilite", "toc", "md_in_html", "tables"]

[[taxonomies]]
key = "tags"
singular = "tag"
plural = "tags"

[[taxonomies]]
key = "topic"
singular = "topic"
plural = "topics"
possible_terms = ["Thoughts", "Personal", "News"]

Available options

Table 1. Global Section
Option	Type	Default	Description
`title`	string	MySite	Page title
`url`	string	https://example.com	Base URL for page. It is used to construct relative URLs to pages (e.g. by `ref` macro).
`language`	string	en	Language code for your page
`timezone`	string	+0000	Timezone which is used by some functions to generate localized times.
`plugins_path`	string	plugins	Directory where your custom plugins are stored
`plugins_disabled`	list of strings		List of disabled plugins
`content`	string	content	Directory where you store sources of your pages
`output`	string	_output	Directory stag will generate the site
`cache`	string	.cache	Directory where stag will cache some generation results to speed up subsequent builds
`no_cache`	bool	False	Disable caching

Table 2. Table: [template]
Option	Type	Default	Description
`name`	string	themes/default	Directory to currently used theme
`templates`	table	`[template.templates] page = "page" list = "list" taxonomy = "taxonomy`	Table which contains a mapping of page types to template names. You can also change page type individually for each page (see Template Name Deduction).

Table 3. Table: [user]
Option	Type	Default	Description
`any name`	string		`[user]` table is a special table where you can place any additional variables useful for your site.

Table 4. List of Tables: [[taxonomies]]
Option	Type	Description
`key`	string	Name of taxonomy
`singular`	string	Singular form of taxonomy name
`plural`	string	Plural form of taxonomy name
`possible_terms`	list of strings	When specified, this limits possible terms for used for this taxonomy (when a term from outside of this list is used, Stag will produce an error)

Note	`[[taxonomies]]` is a list of tables (one table per taxonomy).

Plugins

[plugins] table contains subtables with options for specific plugins. Each plugin defines its own set of options (if any). Please see Plugin List for a documentation of options available for built-in plugins. If you’re using a third-party plugin, please refer to its documentation.