howto/lektor.md

-Lektor Debian Package lives on the Debian gitlab repository: https://salsa.debian.org/debian/lektor
+[Lektor][] is a static website generator written in Python, we use it to
+generate most of the websites of the Tor Project.
 
-The package is maintained and updated when a new Lektor version comes up.
+[Lektor]: https://github.com/lektor/lektor
 
-Lektor needs a small dependency that is also packaged for Debian and lives at: https://salsa.debian.org/debian/python-inifile/
+[[_TOC_]]
 
-This is a small python library to handle INI files.
+# Tutorial
+
+## Build a Lektor project on your machine
+
+See [this page](https://gitlab.torproject.org/tpo/web/wiki/-/wikis/Compiling-a-local-version-of-the-website)
+on the Web team wiki.
+
+## Build a basic Lektor website in GitLab CI
+
+To enable automatic builds of a Lektor project in GitLab CI, add this snippet
+in `.gitlab.ci-yml`, at the root of the project:
+
+	include:
+	  - project: tpo/tpa/ci-templates
+		file:
+		  - lektor.yml
+		  - pages-deploy.yml
+
+The jobs defined in `lektor.yml` will spawn a container to build the site, and
+`pages-deploy.yml` will deploy the build artifacts to GitLab Pages.
+
+See [howto/gitlab](howto/gitlab#publishing-gitlab-pages) for more details on
+publishing to GitLab Pages.
+
+# How-to
+
+## Submit a website contribution
+
+### As an occasional contributor
+
+The first step is to [get a GitLab account](howto/gitlab#how-to-get-an-account).
+
+This will allow you to fork the Lektor project in your personal GitLab
+namespace, where you can push commits with your changes.
+
+As you do this, GitLab CI will continuously build a copy of the website with
+your changes and publish it to GitLab Pages. The location where these Pages are
+hosted can be displayed by navigation to the project Settings > Pages.
+
+When you are satisfied, you can submit a Merge Request and one of the website
+maintainers will evaluate the proposed changes.
+
+### As a regular contributor
+
+As someone who expects to submit contributions on a regular basis to one of the
+Tor Project websites, the first step is to request access. This can be done by
+joining the `#tor-www` channel on IRC and asking!
+
+The access level granted for website content contributors is normally
+*Developper*. This role grants the ability to push new branches to the GitLab
+project and submit Merge Requests to the default `main` branch.
+
+When a Merge Request is created, a CI pipeline status widget will appear under
+the description, above the discussion threads. If GitLab CI succeeds building
+the branch, it will publish the build artifacts and display a **View app**
+button. Clicking the button will navigate to the build result hosted on
+`review.torproject.net`.
+
+Once the branch is deleted, after the Merge Request is accepted, for example,
+the build artifacts are automatically unpublished.
+
+## Pager playbook
+
+<!-- information about common errors from the monitoring system and -->
+<!-- how to deal with them. this should be easy to follow: think of -->
+<!-- your future self, in a stressful situation, tired and hungry. -->
+
+## Disaster recovery
+
+<!-- what to do if all goes to hell. e.g. restore from backups? -->
+<!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
+<!-- "Installation" below but some pointers. -->
+
+# Reference
+
+## Installation
+
+<!-- how to setup the service from scratch -->
+
+## SLA
+
+<!-- this describes an acceptable level of service for this service -->
+
+## Design
+
+### GitLab CI builds
+
+### Deployments
+
+### Review apps
+
+## Issues
+
+<!-- such projects are never over. add a pointer to well-known issues -->
+<!-- and show how to report problems. usually a link to the bugtracker -->
+
+There is no issue tracker specifically for this project, [File][] or
+[search][] for issues in the [team issue tracker][search].
+
+ [File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
+ [search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues
+
+## Maintainer, users, and upstream
+
+<!-- document who deployed and operates this service, who the users -->
+<!-- are, who the upstreams are, if they are still active, -->
+<!-- collaborative, how do we keep up to date, -->
+
+## Monitoring and testing
+
+<!-- describe how this service is monitored and how it can be tested -->
+<!-- after major changes like IP address changes or upgrades. describe -->
+<!-- CI, test suites, linting, how security issues and upgrades are -->
+<!-- tracked -->
+
+## Logs and metrics
+
+<!-- where are the logs? how long are they kept? any PII? -->
+<!-- what about performance metrics? same questions -->
+
+## Backups
+
+<!-- does this service need anything special in terms of backups? -->
+<!-- e.g. locking a database? special recovery procedures? -->
+
+## Other documentation
+
+<!-- references to upstream documentation, if relevant -->
+
+# Discussion
+
+## Overview
+
+<!-- describe the overall project. should include a link to a ticket -->
+<!-- that has a launch checklist -->
+
+<!-- if this is an old project being documented, summarize the known -->
+<!-- issues with the project. to quote the "audit procedure":
+
+ 5. When was the last security review done on the project? What was
+    the outcome? Are there any security issues currently? Should it
+    have another security review?
+
+ 6. When was the last risk assessment done? Something that would cover
+    risks from the data stored, the access required, etc.
+
+ 7. Are there any in-progress projects? Technical debt cleanup?
+    Migrations? What state are they in? What's the urgency? What's the
+    next steps?
+
+ 8. What urgent things need to be done on this project?
+
+-->
+
+## Goals
+
+<!-- include bugs to be fixed -->
+
+### Must have
+
+### Nice to have
+
+### Non-Goals
+
+## Approvals required
+
+<!-- for example, legal, "vegas", accounting, current maintainer -->
+
+## Proposed Solution
+
+## Cost
+
+## Alternatives considered
+
+<!-- include benchmarks and procedure if relevant -->