mirror of https://github.com/lektor/lektor-website.git

Ionuț Ciocîrlan
2020-03-20 11145a25bea4c81d818e2bfaec978126682651a2
commit | author | age
b5baa0 1 title: Project File
AR 2 ---
3 summary: Covers everything about the project file in Lektor.
4 ---
5 body:
6
7 The project file holds the main configuration of the project and is used to
8 identify the project for the user interface.  The project file is an INI file
75b713 9 (UTF-8 encoded like everything else in Lektor) and the minimal content is the
AR 10 name of the project:
b5baa0 11
AR 12 ```ini
13 [project]
14 name = My Fancy Project
15 ```
16
17 The name of the file can be arbitrary but must have the `.lektorproject`
18 extension or Lektor will not be able to find it.  When Lektor looks for a
19 project it looks upwards from the current folder until it finds a single
be4d2e 20 file with the `.lektorproject` extension and that's then the root of the project.
b5baa0 21
4fa93e 22 !! It's possible to build a Lektor project in the absence of a Project file,
J 23 but this usage is heavily discouraged.  It exists primarily for quick
a6b835 24 testing situations.  But don't be confused if you encounter a Lektor project
AR 25 that does not come with a corresponding project file.
26
b5baa0 27 ## Config Sections
AR 28
4fa93e 29 Within the project file there are various configuration sections.  The
b5baa0 30 following sections currently exist:
AR 31
32 ### `[project]`
33
34 This section controls some basics about the project:
35
36 `name`
37 > This is the human readable name of the project.  It's used in various
38 > places where the system wants to show the context of the operations.  For
39 > instance the admin panel will display this to indicate which project is
40 > being worked on.
41
42 `locale`
43 > This is the default locale of the website.  This defaults to `en_US` and
44 > can be changed to many others.  Most locales of the CLDR project are
45 > supported.  This information is for instance used to format dates.
46
47 `url`
48 > This is the full URL of the website.  If set this information can be used
49 > to enable the `external` URL generation parameter.  Lektor tries hard to
50 > make websites work in a way where this information is not necessary but
51 > some systems might need it.  For instance sitemaps require full URLs and
52 > not having them would be a violation of the specification.
53
b5dfaf 54 `url_style`
AR 55 > This controls the style of generated URL references through the
56 > [url_to :ref](../../api/utils/url-to/) function or filters.  The default
57 > value for this is `relative`.  The following values are possible:
58 >
59 > | Value      | Behavior
60 > | ---------- | -----------
61 > | `relative` | URLs are generated relative to the currently active page.
62 > | `absolute` | URLs are generated absolute (relative to root page)
63 > | `external` | URLs are generated with the fully canonical URL (external).
64 >
65 > There are advantages and disadvantages to all styles.  `relative` has the
66 > benefit that it works without any configuration no matter where you deploy
67 > to.  The downside is that you cannot have a page appear on multiple paths
68 > which for instance breaks custom error pages.  `absolute` is useful for
69 > situations where you have custom error pages and you generally know a bit
70 > about the server you are deploying to.  `external` generally makes not a lot
71 > of sense as default setting but exists for consistency's sake.
72 >
73 > For individual URLs that are generated with the [url_to
74 > :ref](../../api/utils/url-to/) function it's possible to override the
75 > default URL style.
76
b5baa0 77 `path`
AR 78 > This setting can be used to configure a different path for the project
79 > tree.  This requires a bit of explanation:
80 >
81 > If this is not set (which is the default) then Lektor will find the
82 > content files right next to the project file.  However in some situations
83 > you might want to move a project file to a completely different location
84 > for instance because you want to have settings in there that you do not
85 > want to put into version control.  In that case you can set the `path`
86 > in the file to a path (absolute or relative to the project file) which
87 > resolves to the project tree.
88 >
89 > Note that if this setting is used some functionality in the desktop app
90 > might no longer work (for instance opening `.lr` files with a double click).
91
e538a8 92 `excluded_assets`
AJJD 93 > A list of file names or Unix shell-style wildcards, separated by commas.
94 > The wildcard syntax follows [fnmatch](https://docs.python.org/2/library/fnmatch.html).
95 >
96 > By default, filenames beginning with "_" or "." are not copied from the
97 > `assets` directory to the output directory. Exclude *additional* files with
98 > the `excluded_assets` option.
99
100 `included_assets`
101 > A comma-separated list of file names or Unix shell-style wildcards, specifying
102 > files that should be copied from the `assets` directory to the output
103 > directory even if they begin with "_" or "." (the default exclusion patterns)
104 > or match your custom `excluded_assets` pattern. The wildcard syntax follows
105 > [fnmatch](https://docs.python.org/2/library/fnmatch.html).
106
b5baa0 107 Example:
AR 108
109 ```ini
110 [project]
111 name = My Website
112 url = https://www.mywebsite.invalid/
113 locale = de_DE
e538a8 114 excluded_assets = *.backup, *~
AJJD 115 included_assets = _special_file
b5baa0 116 ```
AR 117
118 ### `[packages]`
119
120 This section controls the packages (plugins) that should be installed for
121 this project.  It's a simple key/value list where the key is the plugin
122 name and the value is the version number.
123
124 Example:
125
126 ```ini
127 [packages]
128 lektor-webpack-support = 0.1
129 ```
130
131 ### `[servers.*]`
132
133 This section can be repeated and each instance sets up a server.  The `*`
134 needs to be replaced with the ID of the server.  This ID is used by the
135 command line tool to select the server to deploy to.  For more information
136 about this see the [Deployment Guide :ref](../../deployment/)
137
138 `name`
139 > Human readable name for this server (shown in the UI)
140
141 `target`
142 > The target URL for the server.  This URL is specific to the deployment
143 > method that is being used.  For a list of which URLs are supported refer
144 > to the deployment guides.
145
146 `enabled`
147 > This setting can be used to enable/disable the server.  The default is `yes`.
148
149 `default`
150 > This can be used to set a server to be used by default.  If only one server
151 > is configured it's an implicit default.
152
153 Example:
154
155 ```ini
156 [servers.production]
157 name = Production
158 enabled = yes
159 default = yes
160 target = rsync://server/path/to/folder
161 ```
162
163 ### `[alternatives.*]`
164
165 This configures [Alternatives :ref](../../content/alts/).  It is repeated for
166 each intended alternative.  The default behavior is that alternatives are
167 disabled.
168
169 `name`
170 > The human readable name for the alternative.  The admin interface uses this.
171
172 `url_prefix`
173 > A prefix that is added in front of all URLs to identify this alternative.
174
175 `url_suffix`
176 > A suffix that is added behind all URLs to enable this alternative.  This is
177 > currently discouraged compared to the URL prefix as it might not yet work
178 > in all situations properly.
179
180 `primary`
181 > If this is set to `true` then the alternative is selected as primary.  For
182 > more information about this refer to the guide.
183
184 `locale`
185 > This setting can override the global site locale for a specific alternative.
186
187 Example:
188
189 ```ini
190 [alternatives.en]
191 name = English
192 primary = yes
193 locale = en_US
194
195 [alternatives.fr]
196 name = French
197 url_prefix = /fr/
198 locale = fr
199 ```
fe3fe6 200
AR 201 ### `[attachment_types]`
202 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.
203
204 Example:
205
206 ```ini
207 [attachment_types]
208 ; <.file-ext> = <type>
209 .gpx = gpx
210 .ogv = video
211 ```