howto/lektor.md

@@ -82,17 +82,65 @@ the build artifacts are automatically unpublished.
 
 ## Installation
 
-<!-- how to setup the service from scratch -->
+Creating a new Lektor website is out of scope for this document.
 
-## SLA
+Check out the [Quickstart](https://www.getlektor.com/docs/quickstart/) page in
+the Lektor documentation to get started.
 
-<!-- this describes an acceptable level of service for this service -->
+## SLA
 
 ## Design
 
-### GitLab CI builds
+The workflows around Lektor websites is heavily dependant on GitLab CI: it
+handles building the sites, running tests and deploying them to various
+environments including staging and production.
+
+See [service/ci](service/ci) for general documentation about GitLab CI.
+
+### CI build/test pipelines
+
+The [lektor.yml][] CI template is used to configure pipelines for build and
+testing Lektor website projects. Including this into the project's
+`gitlab-ci.yml` is usually sufficient for GitLab CI to "do the right thing".
+
+There are several elements that can be used to customize the build process:
+
+ * `LEKTOR_BUILD_FLAGS`: this variable accepts a space separated list of
+   flags to append to the `lektor build` command. For example, setting this
+   variable to `npm` will cause `-f npm` to be appended to the build command.
+
+ * `LEKTOR_PARTIAL_BUILD`: this variable can be used to alter the build process
+   occuring on non-default branches and l10n-staging jobs. When set (to
+   anything), it will append commands defined in `.setup-lektor-partial-build`
+   to the job's `before_script`. Its main purpose is to pre-process website
+   sources to reduce the build times by trimming less-essential content which
+   contribute a lot to build duration. See the [web/tpo project CI][] for an
+   example.
+
+ * `TRANSLATION_BRANCH`: this variable must contain the name of the
+   [translation repository][] branch used to store localization files. If this
+   variable is absent, the website will be built without l10n.
+
+[lektor.yml]: https://gitlab.torproject.org/tpo/tpa/ci-templates/-/blob/main/lektor.yml
+[translation repository]: https://gitlab.torproject.org/tpo/translation
+[web/tpo]: https://gitlab.torproject.org/tpo/web/tpo/-/blob/main/.gitlab-ci.yml
+
+Another method of customizing the build process is by overriding keys from the
+`.lektor` hash (defined in the `lektor.yml` template) from their own
+`.gitlab-ci.yml` file.
+
+For example, this hash, added to `gitlab-ci.yml` will cause the jobs defined in
+the template to use a different image, and set `GIT_STRATEGY` to `clone`.
+
+    .lektor:
+      image: ubuntu:latest
+      variables:
+        GIT_STRATEGY: clone
+
+This is in addition to the ability to override the named job parameters
+directly in `.gitlab-ci.yml`.
 
-### Deployments
+### CD pipelines
 
 ### Review apps