Configuration

Liara is driven through configuration files. The main file is config.yaml, which can reference other configuration files. To get the full default configuration, use liara create-config. Nested configuration options can be either provided by actually nesting them in the YAML file, or by . as the separator. For example, the following two configurations are equivalent:

build:
  cache:
    type: redis
    redis:
      expiration_time: 60

build:
  cache.type: redis
  cache.redis.expiration_time: 60

Directory settings

  • content_directory: The root directory for all content. Output paths will be build relative to this folder. See Content for more details.

  • resource_directory: The folder containing resources, i.e. SASS or other files that need to get processed before they can be written to the output. See Resources for more details.

  • static_directory: The folder containing static files, for instance downloads, images, videos etc.

  • output_directory: The output directory.

  • generator_directory: The folder containing Generators.

  • plugin_directories: A list of directories to be scanned for Plugins.

    Added in version 2.5.

Build settings

  • build.clean_output: If set to True, the output directory will be deleted on every build.

  • build.cache_directory: The directory where the cache will be stored. Only used by db and fs caches.

    Deprecated since version 2.2: Use build.cache.db.directory and build.cache.fs.directory instead.

  • build.cache_type: The cache type to use.

    Deprecated since version 2.2: Use build.cache.type.

  • build.cache.type: The cache type to use. One of:

    • db uses a local database cache, which stores everything in a single file.

    • fs stores files in a directory, using one file per cache entry.

    • redis uses Redis as the backend.

    • none disables caching

    Note

    The fs cache is a good default for most users. If creating files is expensive, db will perform better as it stores all data in a single file. Both fs and db caches are single-user only and don’t remove old entries – if the cache grows too big, you’ll want to delete the cache directory or clear it using liara cache clear.

    redis is useful if you have an existing instance already, want to benefit from automatic cache clearing, or have multiple concurrent instances of Liara (for example, an automated build server in addition to a local client.)

  • build.resource.sass.compiler: The compiler to use for SASS files:

    • cli uses the sass command, which must be available in the path.

    • libsass uses libsass, which is deprecated, but does not depend on external binaries.

    Added in version 2.3.4.

Note

Caching is imperfect: In some rare cases, you may see stale content. You can use liara build --no-cache or liara cache clear if you’re running into issues with incorrect caching (and please report a bug in those cases.) Generally speaking, updating Liara, a dependency or a plugin should be followed by clearing the cache.

Database cache options

These options are only available when the cache_type is set to db:

  • build.cache.db.directory: The directory where the cache will be stored.

Filesystem cache options

These options are only available when the cache_type is set to fs:

  • build.cache.fs.directory: The directory where the cache will be stored.

Redis cache options

These options are only available when the cache_type is set to redis:

  • build.cache.redis.host: The Redis host string (default: localhost)

  • build.cache.redis.port: The Redis port (default: 6379)

  • build.cache.redis.db: The Redis DB (default: 0)

  • build.cache.redis.expiration_time: The expiration time for cache values in minutes (default: 60)

Content settings

  • content.filters: Specifies which content filters will be applied while discovering content.

  • template: The template definition to apply to the content.

  • collections: Points to the file containing the collection definitions.

  • feeds: Points to the file containing the feed definitions.

  • indices: Points to the file containing the index definitions.

  • metadata: Points to the file containing the site metadata.

  • relaxed_date_parsing: If enabled, metadata fields named date will be processed twice. By default, Liara assumes that date contains a markup-specific date field. If this option is on, and the date field is pointing at a string, Liara will try to parse that string into a timestamp.

  • allow_relative_links: Allow the usage of relative links in content files. This has a negative build time impact on any file containing relative links and is thus recommended to be left off.

  • content.markdown: Configures the Markdown processor. Liara uses Python-Markdown with PyMdown Extensions for Markdown processing. You can set the extension list, the extension configuration, and the output format here.

    This option is a dictionary with three keys:

    • extensions: A list of extensions to enable.

    • config: This is mapped to the extension_config variable and can be used to fine-tune the extension behavior.

    • output: Configures the output format. The default is html5.

    Added in version 2.5.

Other settings

  • routes.static: Points to the file containing static routes.

  • ignore_files: A list of file patterns to ignore, for instance, ["*.backup"]. The default is *~ which ignores all files with a trailing ~. The file matching supports Unix-style wildcards: ? matches a single character, * matches everything.