19 files changed, 124 insertions, 57 deletions

diff --git a/docs/AUTOMATIC_BOOT_ASSESSMENT.md b/docs/AUTOMATIC_BOOT_ASSESSMENT.md
index 83acdab446..6f7182a4b3 100644
--- a/docs/AUTOMATIC_BOOT_ASSESSMENT.md
+++ b/docs/AUTOMATIC_BOOT_ASSESSMENT.md
@@ -1,3 +1,7 @@
+---
+title: Automatic Boot Assessment
+---
+
 # Automatic Boot Assessment
 
 systemd provides support for automatically reverting back to the previous
diff --git a/docs/BLOCK_DEVICE_LOCKING.md b/docs/BLOCK_DEVICE_LOCKING.md
index ceb060c0c9..58178ad2f7 100644
--- a/docs/BLOCK_DEVICE_LOCKING.md
+++ b/docs/BLOCK_DEVICE_LOCKING.md
@@ -1,3 +1,7 @@
+---
+title: Locking Block Device Access
+---
+
 # Locking Block Device Access
 
 *TL;DR: Use BSD file locks
diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md
index a0c7f39970..50488ee97a 100644
--- a/docs/BOOT_LOADER_INTERFACE.md
+++ b/docs/BOOT_LOADER_INTERFACE.md
@@ -1,3 +1,7 @@
+---
+title: The Boot Loader Interface
+---
+
 # The Boot Loader Interface
 
 systemd can interface with the boot loader to receive performance data and
diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md
index 3724f78a80..3612ff1d33 100644
--- a/docs/BOOT_LOADER_SPECIFICATION.md
+++ b/docs/BOOT_LOADER_SPECIFICATION.md
@@ -1,3 +1,7 @@
+---
+title: The Boot Loader Specification
+---
+
 # The Boot Loader Specification
 
 _TL;DR: Currently there's little cooperation between multiple distributions in dual-boot (or triple, ... multi-boot) setups, and we'd like to improve this situation by getting everybody to commit to a single boot configuration format that is based on drop-in files, and thus is robust, simple, works without rewriting configuration files and is free of namespace clashes._
diff --git a/docs/CGROUP_DELEGATION.md b/docs/CGROUP_DELEGATION.md
index ed23a0a142..8bf1b698fc 100644
--- a/docs/CGROUP_DELEGATION.md
+++ b/docs/CGROUP_DELEGATION.md
@@ -1,3 +1,7 @@
+---
+title: Control Group APIs and Delegation
+---
+
 # Control Group APIs and Delegation
 
 *Intended audience: hackers working on userspace subsystems that require direct
@@ -17,7 +21,7 @@ container managers.
 
 Before you read on, please make sure you read the low-level [kernel
 documentation about
-cgroupsv2](https://www.kernel.org/doc/Documentation/cgroup-v2.txt). This
+cgroup v2](https://www.kernel.org/doc/Documentation/cgroup-v2.txt). This
 documentation then adds in the higher-level view from systemd.
 
 This document augments the existing documentation we already have:
@@ -34,8 +38,8 @@ wiki documentation into this very document, too.)
 ## Two Key Design Rules
 
 Much of the philosophy behind these concepts is based on a couple of basic
-design ideas of cgroupsv2 (which we however try to adapt as far as we can to
-cgroupsv1 too). Specifically two cgroupsv2 rules are the most relevant:
+design ideas of cgroup v2 (which we however try to adapt as far as we can to
+cgroup v1 too). Specifically two cgroup v2 rules are the most relevant:
 
 1. The **no-processes-in-inner-nodes** rule: this means that it's not permitted
 to have processes directly attached to a cgroup that also has child cgroups and
@@ -58,45 +62,45 @@ your container manager creates and manages cgroups in the system's root cgroup
 you violate rule #2, as the root cgroup is managed by systemd and hence off
 limits to everybody else.
 
-Note that rule #1 is generally enforced by the kernel if cgroupsv2 is used: as
+Note that rule #1 is generally enforced by the kernel if cgroup v2 is used: as
 soon as you add a process to a cgroup it is ensured the rule is not
-violated. On cgroupsv1 this rule didn't exist, and hence isn't enforced, even
+violated. On cgroup v1 this rule didn't exist, and hence isn't enforced, even
 though it's a good thing to follow it then too. Rule #2 is not enforced on
-either cgroupsv1 nor cgroupsv2 (this is UNIX after all, in the general case
+either cgroup v1 nor cgroup v2 (this is UNIX after all, in the general case
 root can do anything, modulo SELinux and friends), but if you ignore it you'll
 be in constant pain as various pieces of software will fight over cgroup
 ownership.
 
-Note that cgroupsv1 is currently the most deployed implementation, even though
+Note that cgroup v1 is currently the most deployed implementation, even though
 it's semantically broken in many ways, and in many cases doesn't actually do
-what people think it does. cgroupsv2 is where things are going, and most new
-kernel features in this area are only added to cgroupsv2, and not cgroupsv1
-anymore. For example cgroupsv2 provides proper cgroup-empty notifications, has
+what people think it does. cgroup v2 is where things are going, and most new
+kernel features in this area are only added to cgroup v2, and not cgroup v1
+anymore. For example cgroup v2 provides proper cgroup-empty notifications, has
 support for all kinds of per-cgroup BPF magic, supports secure delegation of
 cgroup trees to less privileged processes and so on, which all are not
-available on cgroupsv1.
+available on cgroup v1.
 
 ## Three Different Tree Setups 🌳
 
 systemd supports three different modes how cgroups are set up. Specifically:
 
-1. **Unified** — this is the simplest mode, and exposes a pure cgroupsv2
+1. **Unified** — this is the simplest mode, and exposes a pure cgroup v2
 logic. In this mode `/sys/fs/cgroup` is the only mounted cgroup API file system
 and all available controllers are exclusively exposed through it.
 
-2. **Legacy** — this is the traditional cgroupsv1 mode. In this mode the
+2. **Legacy** — this is the traditional cgroup v1 mode. In this mode the
 various controllers each get their own cgroup file system mounted to
 `/sys/fs/cgroup/<controller>/`. On top of that systemd manages its own cgroup
 hierarchy for managing purposes as `/sys/fs/cgroup/systemd/`.
 
 3. **Hybrid** — this is a hybrid between the unified and legacy mode. It's set
 up mostly like legacy, except that there's also an additional hierarchy
-`/sys/fs/cgroup/unified/` that contains the cgroupsv2 hierarchy. (Note that in
+`/sys/fs/cgroup/unified/` that contains the cgroup v2 hierarchy. (Note that in
 this mode the unified hierarchy won't have controllers attached, the
 controllers are all mounted as separate hierarchies as in legacy mode,
-i.e. `/sys/fs/cgroup/unified/` is purely and exclusively about core cgroupsv2
+i.e. `/sys/fs/cgroup/unified/` is purely and exclusively about core cgroup v2
 functionality and not about resource management.) In this mode compatibility
-with cgroupsv1 is retained while some cgroupsv2 features are available
+with cgroup v1 is retained while some cgroup v2 features are available
 too. This mode is a stopgap. Don't bother with this too much unless you have
 too much free time.
 
@@ -116,7 +120,7 @@ to talk of one specific cgroup and actually mean the same cgroup in all
 available controller hierarchies. E.g. if we talk about the cgroup `/foo/bar/`
 then we actually mean `/sys/fs/cgroup/cpu/foo/bar/` as well as
 `/sys/fs/cgroup/memory/foo/bar/`, `/sys/fs/cgroup/pids/foo/bar/`, and so on.
-Note that in cgroupsv2 the controller hierarchies aren't orthogonal, hence
+Note that in cgroup v2 the controller hierarchies aren't orthogonal, hence
 thinking about them as orthogonal won't help you in the long run anyway.
 
 If you wonder how to detect which of these three modes is currently used, use
@@ -168,7 +172,7 @@ cgroup `/foo.slice/foo-bar.slice/foo-bar-baz.slice/quux.service/`.
 By default systemd sets up four slice units:
 
 1. `-.slice` is the root slice. i.e. the parent of everything else. On the host
-   system it maps directly to the top-level directory of cgroupsv2.
+   system it maps directly to the top-level directory of cgroup v2.
 
 2. `system.slice` is where system services are by default placed, unless
    configured otherwise.
@@ -187,8 +191,8 @@ above are just the defaults.
 
 Container managers and suchlike often want to control cgroups directly using
 the raw kernel APIs. That's entirely fine and supported, as long as proper
-*delegation* is followed. Delegation is a concept we inherited from cgroupsv2,
-but we expose it on cgroupsv1 too. Delegation means that some parts of the
+*delegation* is followed. Delegation is a concept we inherited from cgroup v2,
+but we expose it on cgroup v1 too. Delegation means that some parts of the
 cgroup tree may be managed by different managers than others. As long as it is
 clear which manager manages which part of the tree each one can do within its
 sub-graph of the tree whatever it wants.
@@ -217,7 +221,7 @@ guarantees:
    hierarchy (in unified and hybrid mode) as well as on systemd's own private
    hierarchy (in legacy and hybrid mode). It won't pass ownership of the legacy
    controller hierarchies. Delegation to less privileges processes is not safe
-   in cgroupsv1 (as a limitation of the kernel), hence systemd won't facilitate
+   in cgroup v1 (as a limitation of the kernel), hence systemd won't facilitate
    access to it.
 
 3. Any BPF IP filter programs systemd installs will be installed with
@@ -322,19 +326,19 @@ to work on that, and widen your horizon a bit. You are welcome.
 systemd supports a number of controllers (but not all). Specifically, supported
 are:
 
-* on cgroupsv1: `cpu`, `cpuacct`, `blkio`, `memory`, `devices`, `pids`
-* on cgroupsv2: `cpu`, `io`, `memory`, `pids`
+* on cgroup v1: `cpu`, `cpuacct`, `blkio`, `memory`, `devices`, `pids`
+* on cgroup v2: `cpu`, `io`, `memory`, `pids`
 
-It is our intention to natively support all cgroupsv2 controllers as they are
-added to the kernel. However, regarding cgroupsv1: at this point we will not
+It is our intention to natively support all cgroup v2 controllers as they are
+added to the kernel. However, regarding cgroup v1: at this point we will not
 add support for any other controllers anymore. This means systemd currently
-does not and will never manage the following controllers on cgroupsv1:
+does not and will never manage the following controllers on cgroup v1:
 `freezer`, `cpuset`, `net_cls`, `perf_event`, `net_prio`, `hugetlb`. Why not?
 Depending on the case, either their API semantics or implementations aren't
-really usable, or it's very clear they have no future on cgroupsv2, and we
+really usable, or it's very clear they have no future on cgroup v2, and we
 won't add new code for stuff that clearly has no future.
 
-Effectively this means that all those mentioned cgroupsv1 controllers are up
+Effectively this means that all those mentioned cgroup v1 controllers are up
 for grabs: systemd won't manage them, and hence won't delegate them to your
 code (however, systemd will still mount their hierarchies, simply because it
 mounts all controller hierarchies it finds available in the kernel). If you
@@ -355,9 +359,9 @@ cgroups in them — from previous runs, and be extra careful with them as they
 might still carry settings that might not be valid anymore.
 
 Note a particular asymmetry here: if your systemd version doesn't support a
-specific controller on cgroupsv1 you can still make use of it for delegation,
+specific controller on cgroup v1 you can still make use of it for delegation,
 by directly fiddling with its hierarchy and replicating the cgroup tree there
-as necessary (as suggested above). However, on cgroupsv2 this is different:
+as necessary (as suggested above). However, on cgroup v2 this is different:
 separately mounted hierarchies are not available, and delegation has always to
 happen through systemd itself. This means: when you update your kernel and it
 adds a new, so far unseen controller, and you want to use it for delegation,
@@ -417,7 +421,7 @@ unified you (of course, I guess) need to provide only `/sys/fs/cgroup/` itself.
    arbitrary naming, you might need to escape some of the names (for example,
    you really don't want to create a cgroup named `tasks`, just because the
    user created a container by that name, because `tasks` after all is a magic
-   attribute in cgroupsv1, and your `mkdir()` will hence fail with `EEXIST`. In
+   attribute in cgroup v1, and your `mkdir()` will hence fail with `EEXIST`. In
    systemd we do escaping by prefixing names that might collide with a kernel
    attribute name with an underscore. You might want to do the same, but this
    is really up to you how you do it. Just do it, and be careful.
@@ -462,9 +466,9 @@ unified you (of course, I guess) need to provide only `/sys/fs/cgroup/` itself.
    to get the cgroup for a unit. The method `GetUnitByControlGroup()` may be
    used to get the unit for a cgroup.)
 
-6. ⚡ Think twice before delegating cgroupsv1 controllers to less privileged
+6. ⚡ Think twice before delegating cgroup v1 controllers to less privileged
    containers. It's not safe, you basically allow your containers to freeze the
-   system with that and worse. Delegation is a strongpoint of cgroupsv2 though,
+   system with that and worse. Delegation is a strongpoint of cgroup v2 though,
    and there it's safe to treat delegation boundaries as privilege boundaries.
 
 And that's it for now. If you have further questions, refer to the systemd
diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md
index b3b46cd6d8..da290ecda3 100644
--- a/docs/CODE_OF_CONDUCT.md
+++ b/docs/CODE_OF_CONDUCT.md
@@ -1,3 +1,7 @@
+---
+title: The systemd Community Conduct Guidelines
+---
+
 # The systemd Community Conduct Guidelines
 
 This document provides community guidelines for a safe, respectful, productive, and collaborative place for any person who is willing to contribute to systemd. It applies to all “collaborative spaces”, which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.).
diff --git a/docs/CODE_QUALITY.md b/docs/CODE_QUALITY.md
index be0e13f653..18363f0f1b 100644
--- a/docs/CODE_QUALITY.md
+++ b/docs/CODE_QUALITY.md
@@ -1,3 +1,7 @@
+---
+title: Code Quality Tools
+---
+
 # Code Quality Tools
 
 The systemd project has a number of code quality tools set up in the source
diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index a91e119c4a..7bad3f5d2e 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -1,3 +1,7 @@
+---
+title: Coding Style
+---
+
 # Coding Style
 
 - 8ch indent, no tabs, except for files in `man/` which are 2ch indent,
@@ -126,8 +130,8 @@
   }
   ```
 
-- Unless you allocate an array, `double` is always the better choice
-  than `float`. Processors speak `double` natively anyway, so this is
+- Unless you allocate an array, `double` is always a better choice
+  than `float`. Processors speak `double` natively anyway, so there is
   no speed benefit, and on calls like `printf()` `float`s get promoted
   to `double`s anyway, so there is no point.
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 6cfdd6f179..f40d9a010a 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,3 +1,7 @@
+---
+title: Contributing
+---
+
 # Contributing
 
 We welcome contributions from everyone. However, please follow the following guidelines when posting a GitHub Pull Request or filing a GitHub Issue on the systemd project:
diff --git a/docs/DISTRO_PORTING.md b/docs/DISTRO_PORTING.md
index bcb093fbdc..f8b98bcbae 100644
--- a/docs/DISTRO_PORTING.md
+++ b/docs/DISTRO_PORTING.md
@@ -1,3 +1,7 @@
+---
+title: Porting systemd To New Distributions
+---
+
 # Porting systemd To New Distributions
 
 ## HOWTO
diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md
index 619a57eb3f..99b5b03b68 100644
--- a/docs/ENVIRONMENT.md
+++ b/docs/ENVIRONMENT.md
@@ -1,3 +1,7 @@
+---
+title: Known Environment Variables
+---
+
 # Known Environment Variables
 
 A number of systemd components take additional runtime parameters via
diff --git a/docs/HACKING.md b/docs/HACKING.md
index 17136060ce..b14be72128 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -1,3 +1,7 @@
+---
+title: Hacking on systemd
+---
+
 # Hacking on systemd
 
 We welcome all contributions to systemd. If you notice a bug or a missing
diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md
index 4b37a19455..5b6c085af0 100644
--- a/docs/PORTABLE_SERVICES.md
+++ b/docs/PORTABLE_SERVICES.md
@@ -1,3 +1,7 @@
+---
+title: Portable Services Introduction
+---
+
 # Portable Services Introduction
 
 This systemd version includes a preview of the "portable service"
@@ -85,8 +89,9 @@ If you have portable service image, maybe in a raw disk image called
 
 This command does the following:
 
-1. It dissects the image, checks and validates the `/etc/os-release` data of
-   the image, and looks for all included unit files.
+1. It dissects the image, checks and validates the `/etc/os-release`
+   (or `/usr/lib/os-release`, see below)  data of the image, and looks for
+   all included unit files.
 
 2. It copies out all unit files with a suffix of `.service`, `.socket`,
    `.target`, `.timer` and `.path`. whose name begins with the image's name
@@ -166,8 +171,11 @@ requirements are made for an image that can be attached/detached with
    image. (The implementation will check a couple of other paths too, but it's
    recommended to use these two paths.)
 
-4. The image must contain an os-release file, either in /etc/os-release or
-   /usr/lib/os-release. The file should follow the standard format.
+4. The image must contain an os-release file, either in `/etc/os-release` or
+   `/usr/lib/os-release`. The file should follow the standard format.
+
+5. The image must contain the files `/etc/resolv.conf` and `/etc/machine-id`
+   (empty files are ok), they will be bind mounted from the host at runtime.
 
 Note that generally images created by tools such as `debootstrap`, `dnf
 --installroot=` or `mkosi` qualify for all of the above in one way or
diff --git a/docs/PREDICTABLE_INTERFACE_NAMES.md b/docs/PREDICTABLE_INTERFACE_NAMES.md
index 73d60477cd..b29016f93d 100644
--- a/docs/PREDICTABLE_INTERFACE_NAMES.md
+++ b/docs/PREDICTABLE_INTERFACE_NAMES.md
@@ -1,3 +1,7 @@
+---
+title: Predictable Network Interface Names
+---
+
 # Predictable Network Interface Names
 
 Starting with v197 systemd/udev will automatically assign predictable, stable network interface names for all local Ethernet, WLAN and WWAN interfaces. This is a departure from the traditional interface naming scheme ("eth0", "eth1", "wlan0", ...), but should fix real problems.
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 11794aae63..4bf5ab8dc1 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -1,3 +1,7 @@
+---
+title: Steps to a Successful Release
+---
+
 # Steps to a Successful Release
 
 1. Add all items to NEWS
diff --git a/docs/TRANSIENT-SETTINGS.md b/docs/TRANSIENT-SETTINGS.md
index 89a185b527..0ac77f0497 100644
--- a/docs/TRANSIENT-SETTINGS.md
+++ b/docs/TRANSIENT-SETTINGS.md
@@ -1,3 +1,7 @@
+---
+title: What settings are currently available for transient units?
+---
+
 # What settings are currently available for transient units?
 
 Our intention is to make all settings that are available as unit file settings
diff --git a/docs/TRANSLATORS.md b/docs/TRANSLATORS.md
index 9c45453083..d155c1c875 100644
--- a/docs/TRANSLATORS.md
+++ b/docs/TRANSLATORS.md
@@ -1,3 +1,7 @@
+---
+title: Notes for Translators
+---
+
 # Notes for Translators
 
 systemd depends on the `gettext` package for multilingual support.
diff --git a/docs/UIDS-GIDS.md b/docs/UIDS-GIDS.md
index c59fefc5cd..25345a918f 100644
--- a/docs/UIDS-GIDS.md
+++ b/docs/UIDS-GIDS.md
@@ -1,3 +1,7 @@
+---
+title: Users, Groups, UIDs and GIDs on `systemd` Systems
+---
+
 # Users, Groups, UIDs and GIDs on `systemd` Systems
 
 Here's a summary of the requirements `systemd` (and Linux) make on UID/GID
diff --git a/docs/index.md b/docs/index.md
index 2140253674..ffb30b9634 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,20 +1,11 @@
+---
+title: systemd Documentation
+---
+
 # systemd Documentation
 
-* [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT)
-* [Locking Block Device Access](https://systemd.io/BLOCK_DEVICE_LOCKING)
-* [The Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
-* [The Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
-* [Control Group APIs and Delegation](https://systemd.io/CGROUP_DELEGATION)
-* [The systemd Community Conduct Guidelines](https://github.com/systemd/systemd/blob/master/docs/CODE_OF_CONDUCT.md)
-* [Code Quality Tools](https://systemd.io/CODE_QUALITY)
-* [Coding Style](https://systemd.io/CODING_STYLE)
-* [Contributing](https://github.com/systemd/systemd/blob/master/docs/CONTRIBUTING.md)
-* [Porting systemd To New Distributions](https://systemd.io/DISTRO_PORTING)
-* [Predictable Network Interface Names](https://systemd.io/PREDICTABLE_INTERFACE_NAMES)
-* [Known Environment Variables](https://systemd.io/ENVIRONMENT)
-* [Hacking on systemd](https://systemd.io/HACKING)
-* [Portable Services Introduction](https://systemd.io/PORTABLE_SERVICES)
-* [Steps to a Successful Release](https://systemd.io/RELEASE)
-* [What settings are currently available for transient units?](https://systemd.io/TRANSIENT-SETTINGS)
-* [Notes for Translators](https://systemd.io/TRANSLATORS)
-* [Users, Groups, UIDs and GIDs on `systemd` Systems](https://systemd.io/UIDS-GIDS)
+{% for p in site.pages %}
+  {% if p.url != page.url and p.title %}
+* [{{ p.title }}]({{ p.url | relative_url }})
+  {% endif %}
+{% endfor %}