Edit this page on Github

Your site have a config.yml file that lets you change the default configuration of Spress and create new variables that will be accessible in your template with {{ site.your_variable }}. Some global variables like timezone or safe can be specified in the command line options or flags.

The configuration is using YAML formatted file. Do not use tabs!

Environment configuration: development and production

The environment configuration is useful for writing configuration options for development and production environments. Each Spress site has a config.yml file with the options for the default environment (dev). If you want to set options for production environment you can create a config_prod.yml file with the options that will override values from config.yml. The command line option --env="prod" lets you enable a specific environment.

The pattern for environment configuration filename is config_{environment-name}.yml.

An example for "prod" (production) environment:

$ spress site:build --env=prod

More information and examples available at this blog post.

Default configuration

Spress runs with the default configuration:

debug: false

# Reading
env: 'dev'
drafts: false
text_extensions: [ 'htm', 'html', 'html.twig', 'twig.html', 'js', 'less', 'markdown', 'md', 'mkd', 'mkdn', 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'slim', 'txt', 'xhtml', 'xml' ]
attribute_syntax: 'yaml'
map_converter_extension:
  'html.twig': 'html'
  'twig.html': 'html'
  'twig': 'html'

# Markdown converters
markdown_ext: ['markdown', 'mkd', 'mkdn', 'md']
parsedown_activated: false

# Outputting
include: ['.htaccess']
exclude: []
timezone: 'UTC'                          # e.g. Europe/Madrid
safe: false
permalink: 'pretty'
preserve_path_title: false
no_html_extension: false
layout_ext: ['html.twig', 'twig', 'html']
url: ''                                  # e.g: http://your-domain.local:4000

# Collections
collections:
  posts:
    output: true
    sort_by: 'date'
    sort_type: 'descending'

# Serving
host: '0.0.0.0'
port: 4000
server_watch_ext: ['html', 'htm', 'xml']

# Plugin manager
plugin_manager_builder:
  exclude_path: ['tests', 'Tests']
Name Type Description
attribute_syntax string Format for declaration of attributes. Values: yaml or json.
collections array Defines the collections for the content.
debug boolean Enables debug mode.
drafts boolean Include drafts in the generated site.
env string The name of environment.
exclude array Force to exclude files or directories from src/content folder. e.g: ['posts'].
include array Force to include files or directories. e.g: ['/home/static/pages'].
host string Listen at the given hostname. Used with site:build --server command.
map_converter_extension array Spress >= 2.1 Map filename extention to another one. e.g: .twig to .html. This feature lets you work more appropriately with pages using IDEs that have support for Twig syntax.
markdown_ext array For Markdown converter, this is a list of file extensions that will be considered as Markdown files.
layout_ext array File extensions that will be considered as layout templates.
parsedown_activated boolean Activates Parsedown as default Markdown converter instead of Michel Fortin converter - Parsedown is 3-4 times faster than Markdown.
permalink string The style of the permalinks.
plugin_manager_builder array Spress >= 2.1.3 Directives for plugin manager builder. See more details.
port integer Listen on the given port. Used with site:build --server command.
preserve_path_title boolean Set to true in case of you want to preserve the title extracted from the filename path over the Front matter title attribute.
no_html_extension boolean Spress >= 2.1.0 Set to true in case of you want to force the "extensionless" mode from pretty permalink style with custom permalinks.
safe boolean Disable site plugins.
text_extensions array File extensions that will be considered as not binary files.
timezone string Set the Timezone. See more timezones in PHP.
server_watch_ext array Array of file extensions that will trigger auto-regeneration or request.
url string URL base of your site. This is useful for scenarios where a site isn't available from the domain root. Example of use in a template: <link href="{{ site.url }}/css/style.css" rel="stylesheet">

Options for plugin_manager_builder

Name Type Description
exclude_path array Indicates which directories are excluded of the discovering class process. Useful for excluding tests directories.