Project File

The project file holds the main configuration of the project and is used to identify the project for the user interface. The project file is an INI file (UTF-8 encoded like everything else in Lektor) and the minimal content is the name of the project:

[project]
name = My Fancy Project

The name of the file can be arbitrary but must have the .lektorproject extension or Lektor will not be able to find it. When Lektor looks for a project it looks upwards from the current folder until it finds a single file with the .lektorproject extension and that's then the root of the project.

Config Sections

Within the project file there are various configuration sections. The following sections currently exist:

[project]

This section controls some basics about the project:

name

This is the human readable name of the project. It's used in various places where the system wants to show the context of the operations. For instance the admin panel will display this to indicate which project is being worked on.

locale

This is the default locale of the website. This defaults to en_US and can be changed to many others. Most locales of the CLDR project are supported. This information is for instance used to format dates.

url

This is the full URL of the website. If set this information can be used to enable the external URL generation parameter. Lektor tries hard to make websites work in a way where this information is not necessary but some systems might need it. For instance sitemaps require full URLs and not having them would be a violation of the specification.

url_style

This controls the style of generated URL references through the url_to function or filters. The default value for this is relative. The following values are possible:

Value	Behavior
relative	URLs are generated relative to the currently active page.
absolute	URLs are generated absolute (relative to root page)
external	URLs are generated with the fully canonical URL (external).

There are advantages and disadvantages to all styles. relative has the benefit that it works without any configuration no matter where you deploy to. The downside is that you cannot have a page appear on multiple paths which for instance breaks custom error pages. absolute is useful for situations where you have custom error pages and you generally know a bit about the server you are deploying to. external generally makes not a lot of sense as default setting but exists for consistency's sake.

For individual URLs that are generated with the url_to function it's possible to override the default URL style.

path

This setting can be used to configure a different path for the project tree. This requires a bit of explanation:

If this is not set (which is the default) then Lektor will find the content files right next to the project file. However in some situations you might want to move a project file to a completely different location for instance because you want to have settings in there that you do not want to put into version control. In that case you can set the path in the file to a path (absolute or relative to the project file) which resolves to the project tree.

Note that if this setting is used some functionality in the desktop app might no longer work (for instance opening .lr files with a double click).

output_path

Configure the build path for your project. By default, Lektor will detect a proper location depeding on your operation system, only use this setting if you want to set a custom path. The path is relative to the project file, absolute paths are allowed but not portable between distinct filesystems.

excluded_assets

A list of file names or Unix shell-style wildcards, separated by commas. The wildcard syntax follows fnmatch.

By default, filenames beginning with "_" or "." are not copied from the assets directory to the output directory. Exclude additional files with the excluded_assets option.

included_assets

A comma-separated list of file names or Unix shell-style wildcards, specifying files that should be copied from the assets directory to the output directory even if they begin with "_" or "." (the default exclusion patterns) or match your custom excluded_assets pattern. The wildcard syntax follows fnmatch.

Example:

[project]
name = My Website
url = https://www.mywebsite.invalid/
locale = de_DE
excluded_assets = *.backup, *~
included_assets = _special_file

[packages]

This section controls the packages (plugins) that should be installed for this project. It's a simple key/value list where the key is the plugin name and the value is the version number.

Example:

[packages]
lektor-webpack-support = 0.1

[servers.*]

This section can be repeated and each instance sets up a server. The * needs to be replaced with the ID of the server. This ID is used by the command line tool to select the server to deploy to. For more information about this see the Deployment Guide

name

Human readable name for this server (shown in the UI)

target

The target URL for the server. This URL is specific to the deployment method that is being used. For a list of which URLs are supported refer to the deployment guides.

enabled

This setting can be used to enable/disable the server. The default is yes.

default

This can be used to set a server to be used by default. If only one server is configured it's an implicit default.

Example:

[servers.production]
name = Production
enabled = yes
default = yes
target = rsync://server/path/to/folder

[alternatives.*]

This configures Alternatives. It is repeated for each intended alternative. The default behavior is that alternatives are disabled.

name

The human readable name for the alternative. The admin interface uses this.

url_prefix

A prefix that is added in front of all URLs to identify this alternative.

url_suffix

A suffix that is added behind all URLs to enable this alternative. This is currently discouraged compared to the URL prefix as it might not yet work in all situations properly.

primary

If this is set to true then the alternative is selected as primary. For more information about this refer to the guide.

locale

This setting can override the global site locale for a specific alternative.

Example:

[alternatives.en]
name = English
primary = yes
locale = en_US

[alternatives.fr]
name = French
url_prefix = /fr/
locale = fr

[attachment_types]

Lektor does some basic attachment type detection based on file extension. This is what powers the this.attachemnts.images and this.attachments.videos attributes for instance. If the built-in map does not cover your file extension you can extend it or add new attachement types on a project by project basis.

Example:

[attachment_types]
; <.file-ext> = <type>
.gpx = gpx
.ogv = video