From add4a110f7418e913c211e012a23d733375198c6 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 10:38:00 +0200 Subject: [PATCH 01/16] docs: configure editorconfig for css and html --- .editorconfig | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.editorconfig b/.editorconfig index 02196f72be..27bb3755d6 100644 --- a/.editorconfig +++ b/.editorconfig @@ -32,3 +32,11 @@ indent_size = 8 indent_size = 2 indent_style = space max_line_length = 109 + +[docs/**/*.css] +indent_style = space +indent_size = 2 + +[docs/**/*.html] +indent_style = space +indent_size = 2 From 55813558cd438ad2a7a2439dcf53591b5715a1bb Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 13:47:21 +0200 Subject: [PATCH 02/16] docs: remove trailing space --- docs/_includes/head.html | 2 +- docs/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index cccc885518..62f2947bec 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -12,7 +12,7 @@ - + diff --git a/docs/index.md b/docs/index.md index ff26bd3398..b0a9bec67d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,8 +4,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later --- systemd is a suite of basic building blocks for a Linux system. It provides a system and service manager that runs as PID 1 and starts the rest of the system. - -systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and automount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit. + +systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and automount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit. Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution. From f32c5aa16c96e16e1c2b42b315c864654905a867 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 13:16:09 +0200 Subject: [PATCH 03/16] docs: remove invalid link to feed.xml --- docs/_includes/head.html | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 62f2947bec..8473e97b90 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -9,7 +9,6 @@ {% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %} - From d5ce270ced2fe8a9cf08f507a50f7527704388da Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 13:16:25 +0200 Subject: [PATCH 04/16] docs: remove link to missing apple-touch-icon --- docs/_includes/head.html | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 8473e97b90..cf393ca056 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -13,5 +13,4 @@ - From f08446a4f5a6d71dc914611748c906263c834317 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 15:05:01 +0200 Subject: [PATCH 05/16] docs: replace invalid h1 font-weight h1 font weight is defined to be 100 but no font-face definition for weight 100 is included. The browser will use the nearest available font-weight instead. As that is 400, we do specify it explicitly now. --- docs/style.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style.css b/docs/style.css index 6f81452b65..981cdc1b53 100644 --- a/docs/style.css +++ b/docs/style.css @@ -38,7 +38,7 @@ h1, h2, h3, h4, h5, h6 { h1 { text-align: center; font-size: 30px; - font-weight: 100; + font-weight: 400; font-style: normal; margin-bottom: 2rem; } From b336535c6e00c72dcaedc32ff67baa7b92181fdb Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 10:16:15 +0200 Subject: [PATCH 06/16] docs: use whole numbers for circle in page-logo 0.001 is usually rounded to 0 by browsers, still, better to be explicit and save some bytes. --- docs/assets/page-logo.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/assets/page-logo.svg b/docs/assets/page-logo.svg index 72fc5a46cf..a7732afc72 100644 --- a/docs/assets/page-logo.svg +++ b/docs/assets/page-logo.svg @@ -3,5 +3,5 @@ - + From 74de5ddb99ee41ffd7c29d7cc44f05aed0e86bd9 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 10:19:51 +0200 Subject: [PATCH 07/16] docs: remove unneeded font-related attributes from svg logo The font has been vectorized and therefore all font related properties are ignored anyway. --- docs/assets/page-logo.svg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/assets/page-logo.svg b/docs/assets/page-logo.svg index a7732afc72..0adf1ea478 100644 --- a/docs/assets/page-logo.svg +++ b/docs/assets/page-logo.svg @@ -1,7 +1,7 @@ - - + + From 86a3a73bb42331b8e0e4bf3c295ae4801e9cd415 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 13:11:03 +0200 Subject: [PATCH 08/16] docs: adapt theme color meta property The theme color is used on android to style the chrome browser-ui with a color that suits the webpage. Use the dark brand color instead of a random default blue color in order to fit to the rest of the color scheme. --- docs/_includes/head.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index cf393ca056..ae39a3c6aa 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -4,7 +4,7 @@ - + {% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %} From cfcbf1dafb2517239085cc910541951f807f4999 Mon Sep 17 00:00:00 2001 From: Benjamin Franzke Date: Tue, 17 May 2022 16:59:00 +0200 Subject: [PATCH 09/16] docs: replace 
,  and  tags by backticks

Let jekyll render a proper codeblock, instead
of using custom HTML code in markdown.
Also  is deprecated.
---
 docs/DISCOVERABLE_PARTITIONS.md |  8 ++++----
 docs/TRANSLATORS.md             | 12 ++++++------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/DISCOVERABLE_PARTITIONS.md b/docs/DISCOVERABLE_PARTITIONS.md
index 85e858921f..5a4ff4594e 100644
--- a/docs/DISCOVERABLE_PARTITIONS.md
+++ b/docs/DISCOVERABLE_PARTITIONS.md
@@ -42,7 +42,7 @@ Interface](https://systemd.io/BOOT_LOADER_INTERFACE).
 
 | Name | Partition Type UUID | Allowed File Systems | Explanation |
 |------|---------------------|----------------------|-------------|
-| _Root Partition (Alpha)_ | `6523f8ae-3eb1-4e2a-a05a-18b695ae656f` | Any native, optionally in LUKS | On systems with matching architecture, the first partition with this type UUID on the disk containing the active EFI ESP is automatically mounted to the root directory /. If the partition is encrypted with LUKS or has dm-verity integrity data (see below), the device mapper file will be named `/dev/mapper/root`. |
+| _Root Partition (Alpha)_ | `6523f8ae-3eb1-4e2a-a05a-18b695ae656f` | Any native, optionally in LUKS | On systems with matching architecture, the first partition with this type UUID on the disk containing the active EFI ESP is automatically mounted to the root directory `/`. If the partition is encrypted with LUKS or has dm-verity integrity data (see below), the device mapper file will be named `/dev/mapper/root`. |
 | _Root Partition (ARC)_ | `d27f46ed-2919-4cb8-bd25-9531f3c16534` | ditto | ditto |
 | _Root Partition (32-bit ARM)_ | `69dad710-2ce4-4e3c-b16c-21a1d49abed3` | ditto | ditto |
 | _Root Partition (64-bit ARM/AArch64)_ | `b921b045-1df0-41c3-af44-4c6f280d3fae` | ditto | ditto |
@@ -151,14 +151,14 @@ Interface](https://systemd.io/BOOT_LOADER_INTERFACE).
 | _`/usr/` Verity Signature Partition (amd64/x86_64)_ | `e7bb33fb-06cf-4e81-8273-e543b413e2e2` | ditto | ditto |
 | _`/usr/` Verity Signature Partition (x86)_ | `974a71c0-de41-43c3-be5d-5c5ccd1ad2c0` | ditto | ditto |
 | _EFI System Partition_ | `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` | VFAT | The ESP used for the current boot is automatically mounted to `/efi/` (or `/boot/` as fallback), unless a different partition is mounted there (possibly via `/etc/fstab`, or because the Extended Boot Loader Partition — see below — exists) or the directory is non-empty on the root disk.  This partition type is defined by the [UEFI Specification](http://www.uefi.org/specifications). |
-| _Extended Boot Loader Partition_ | `bc13c2ff-59e6-4262-a352-b275fd6f7172` | Typically VFAT | The Extended Boot Loader Partition (XBOOTLDR) used for the current boot is automatically mounted to /boot/, unless a different partition is mounted there (possibly via /etc/fstab) or the directory is non-empty on the root disk. This partition type is defined by the [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION). |
+| _Extended Boot Loader Partition_ | `bc13c2ff-59e6-4262-a352-b275fd6f7172` | Typically VFAT | The Extended Boot Loader Partition (XBOOTLDR) used for the current boot is automatically mounted to `/boot/`, unless a different partition is mounted there (possibly via `/etc/fstab`) or the directory is non-empty on the root disk. This partition type is defined by the [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION). |
 | _Swap_ | `0657fd6d-a4ab-43c4-84e5-0933c84b4f4f` | Swap, optionally in LUKS | All swap partitions on the disk containing the root partition are automatically enabled. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/swap`. This partition type predates the Discoverable Partitions Specification. |
 | _Home Partition_ | `933ac7e1-2eb4-4f13-b844-0e14e2aef915` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/home/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/home`. |
 | _Server Data Partition_ | `3b8f8425-20e0-4f3b-907f-1a25a76f98e8` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/srv/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/srv`. |
 | _Variable Data Partition_ | `4d21b016-b534-45c2-a9fb-5c16e091fd2d` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/var/` — under the condition that its partition UUID matches the first 128 bits of `HMAC-SHA256(machine-id, 0x4d21b016b53445c2a9fb5c16e091fd2d)` (i.e. the SHA256 HMAC hash of the binary type UUID keyed by the machine ID as read from [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html). This special requirement is made because `/var/` (unlike the other partition types listed here) is inherently private to a specific installation and cannot possibly be shared between multiple OS installations on the same disk, and thus should be bound to a specific instance of the OS, identified by its machine ID. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/var`. |
-| _Temporary Data Partition_ | `7ec6f557-3bc5-4aca-b293-16ef5df639d1` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/var/tmp/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/tmp`. Note that the intended mount point is indeed `/var/tmp/`, not `/tmp/`. The latter is typically maintained in memory via tmpfs and does not require a partition on disk. In some cases it might be desirable to make `/tmp/` persistent too, in which case it is recommended to make it a symlink or bind mount to `/var/tmp/`, thus not requiring its own partition type UUID. |
+| _Temporary Data Partition_ | `7ec6f557-3bc5-4aca-b293-16ef5df639d1` | Any native, optionally in LUKS | The first partition with this type UUID on the disk containing the root partition is automatically mounted to `/var/tmp/`. If the partition is encrypted with LUKS, the device mapper file will be named `/dev/mapper/tmp`. Note that the intended mount point is indeed `/var/tmp/`, not `/tmp/`. The latter is typically maintained in memory via `tmpfs` and does not require a partition on disk. In some cases it might be desirable to make `/tmp/` persistent too, in which case it is recommended to make it a symlink or bind mount to `/var/tmp/`, thus not requiring its own partition type UUID. |
 | _Per-user Home Partition_ | `773f91ef-66d4-49b5-bd83-d683bf40ad16` | Any native, optionally in LUKS | A home partition of a user, managed by [`systemd-homed`](https://www.freedesktop.org/software/systemd/man/systemd-homed.html). |
-| _Generic Linux Data Partition_ | `0fc63daf-8483-4772-8e79-3d69d8477de4` | Any native, optionally in LUKS | No automatic mounting takes place for other Linux data partitions. This partition type should be used for all partitions that carry Linux file systems. The installer needs to mount them explicitly via entries in /etc/fstab. Optionally, these partitions may be encrypted with LUKS. This partition type predates the Discoverable Partitions Specification. |
+| _Generic Linux Data Partition_ | `0fc63daf-8483-4772-8e79-3d69d8477de4` | Any native, optionally in LUKS | No automatic mounting takes place for other Linux data partitions. This partition type should be used for all partitions that carry Linux file systems. The installer needs to mount them explicitly via entries in `/etc/fstab`. Optionally, these partitions may be encrypted with LUKS. This partition type predates the Discoverable Partitions Specification. |
 
 Other GPT type IDs might be used on Linux, for example to mark software RAID or
 LVM partitions. The definitions of those GPT types is outside of the scope of
diff --git a/docs/TRANSLATORS.md b/docs/TRANSLATORS.md
index 58708bcd58..2f578cc6f5 100644
--- a/docs/TRANSLATORS.md
+++ b/docs/TRANSLATORS.md
@@ -32,18 +32,18 @@ $ ninja -C build/ systemd-pot
 
 This will generate file `po/systemd.pot` in the source tree.
 
-Then simply copy it to a new ${lang_code}.po file, where
-${lang_code} is the two-letter code for a language
+Then simply copy it to a new `${lang_code}.po` file, where
+`${lang_code}` is the two-letter code for a language
 (possibly followed by a two-letter uppercase country code), according to the
 ISO 639 standard.
 
 In short:
 
-
-$ cp po/systemd.pot po/${lang_code}.po
-

+```
+$ cp po/systemd.pot po/${lang_code}.po
+```
 
-Then edit the new po/${lang_code}.po file (for example,
+Then edit the new `po/${lang_code}.po` file (for example,
 using the `poedit` GUI editor.)
 
 ## Updating an Existing Translation

From 68f0d3ff12520045c144e28417ff347f89fb721a Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 15:57:14 +0200
Subject: [PATCH 10/16] docs: add reasonable difference between h2 and h3
 font-size

---
 docs/style.css | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/style.css b/docs/style.css
index 981cdc1b53..43bc86003a 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -51,7 +51,10 @@ h1 {
 }
 h2 {
   margin-top: 3rem;
-  font-size: 1.2rem;
+  font-size: 1.25rem;
+}
+h3 {
+  font-size: 1.15rem;
 }
 a {
   font-weight: 600;

From bd59f2bf9215d72ade69b5d31dfcbe8a0eb1e6b8 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 14:21:13 +0200
Subject: [PATCH 11/16] docs: respect default browser font-size

16px is default by all browser vendors when
font-setting is defined to be 'medium'.

Scale all font sizes and margins to
based on 16px base size.
---
 docs/style.css | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/style.css b/docs/style.css
index 43bc86003a..fc2bd1c774 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -21,7 +21,7 @@
 html, body {
   margin: 0;
   padding: 0;
-  font-size: 16px;
+  font-size: 1rem;
   font-family: "Heebo", sans-serif;
   font-weight: 400;
   line-height: 1.6;
@@ -31,13 +31,13 @@ body {
   background-color: #f6f5f4;
 }
 h1, h2, h3, h4, h5, h6 {
-  margin: 1rem 0 10px;
+  margin: 1rem 0 0.625rem;
   font-weight: 600;
   line-height: 1.25;
 }
 h1 {
   text-align: center;
-  font-size: 30px;
+  font-size: 1.87rem;
   font-weight: 400;
   font-style: normal;
   margin-bottom: 2rem;
@@ -46,12 +46,12 @@ h1 {
   h1 {
     margin-left: 10%;
     margin-right: 10%;
-    font-size: 38px;
+    font-size: 2.375em;
   }
 }
 h2 {
-  margin-top: 3rem;
   font-size: 1.25rem;
+  margin-top: 2.5em;
 }
 h3 {
   font-size: 1.15rem;
@@ -92,6 +92,8 @@ hr {
 }
 .page-logo > img {
   display: block;
+  width: 12.625em;
+  height: auto;
   margin: 0 auto;
 }
 

From 85b5930b7b3c2099f450438ab02260b41cb3bef3 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 17:05:22 +0200
Subject: [PATCH 12/16] docs: provide a first level headline for the frontpage

 * Provides a nice introduction to the intro paragraph
 * Ensures text of subpages start at the same position as the intro text
   on the homepage
   => less visual "jumps" while navigating
---
 docs/index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/index.md b/docs/index.md
index b0a9bec67d..a4577093d6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,6 +3,8 @@ layout: default
 SPDX-License-Identifier: LGPL-2.1-or-later
 ---
 
+# System and Service Manager
+
 systemd is a suite of basic building blocks for a Linux system. It provides a system and service manager that runs as PID 1 and starts the rest of the system.
 
 systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and automount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit.

From 818e46ae7c3159ef3026930c1a4330f66344b2d1 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 15:54:46 +0200
Subject: [PATCH 13/16] docs: avoid multiple first-level headlines

One document should only contain one main
headline, both for structuring and for
visual reasons.

Relevant cases found via:

  git grep -A2 '^# ' docs/
---
 docs/ARCHITECTURE.md  | 34 ++++++++++++++++++----------------
 docs/HACKING.md       |  2 +-
 docs/RESOLVED-VPNS.md | 10 +++++-----
 3 files changed, 24 insertions(+), 22 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 4559f7c7e5..2ae2ac98e3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -5,19 +5,21 @@ layout: default
 SPDX-License-Identifier: LGPL-2.1-or-later
 ---
 
-# Code Map
+# The systemd Repository Architecture
+
+## Code Map
 
 This section will attempt to provide a high-level overview of the various
 components of the systemd repository.
 
-# Source Code
+## Source Code
 
 Directories in `src/` provide the implementation of all daemons, libraries and
 command-line tools shipped by the project. There are many, and more are
 constantly added, so we will not enumerate them all here — the directory
 names are self-explanatory.
 
-## Shared Code
+### Shared Code
 
 You might wonder what kind of common code belongs in `src/shared/` and what
 belongs in `src/basic/`. The split is like this: anything that is used to
@@ -44,14 +46,14 @@ To summarize:
 `src/journal/` that end up in `libjournal-client.a` convenience library.
 - may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/`
 
-## PID 1
+### PID 1
 
 Code located in `src/core/` implements the main logic of the systemd system (and user)
 service manager.
 
 BPF helpers written in C and used by PID 1 can be found under `src/core/bpf/`.
 
-### Implementing Unit Settings
+#### Implementing Unit Settings
 
 The system and session manager supports a large number of unit settings. These can generally
 be configured in three ways:
@@ -73,12 +75,12 @@ D-Bus messages in `src/shared/bus-unit-util.c`
 So that they are exercised by the fuzzing CI, new unit settings should also be listed in the
 text files under `test/fuzz/fuzz-unit-file/`.
 
-## systemd-udev
+### systemd-udev
 
 Sources for the udev daemon and command-line tool (single binary) can be found under
 `src/udev/`.
 
-## Unit Tests
+### Unit Tests
 
 Source files found under `src/test/` implement unit-level testing, mostly for
 modules found in `src/basic/` and `src/shared/`, but not exclusively. Each test
@@ -91,7 +93,7 @@ and generally safe to run on the host without side effects.
 Ideally, every module in `src/basic/` and `src/shared/` should have a
 corresponding unit test under `src/test/`, exercising every helper function.
 
-## Fuzzing
+### Fuzzing
 
 Fuzzers are a type of unit tests that execute code on an externally-supplied
 input sample. Fuzzers are called `fuzz-*`. Fuzzers for `src/basic/` and
@@ -117,7 +119,7 @@ parallelization; see the links for oss-fuzz in [Code
 quality](https://systemd.io/CODE_QUALITY). For testing and debugging, fuzzers
 can be executed as any other program, including under `valgrind` or `gdb`.
 
-# Integration Tests
+## Integration Tests
 
 Sources in `test/TEST-*` implement system-level testing for executables,
 libraries and daemons that are shipped by the project. They require privileges
@@ -131,40 +133,40 @@ is the case.
 
 See `test/README.testsuite` for more specific details.
 
-# hwdb
+## hwdb
 
 Rules built in the static hardware database shipped by the project can be found
 under `hwdb.d/`. Some of these files are updated automatically, some are filled
 by contributors.
 
-# Documentation
+## Documentation
 
-## systemd.io
+### systemd.io
 
 Markdown files found under `docs/` are automatically published on the
 [systemd.io](https://systemd.io) website using Github Pages. A minimal unit test
 to ensure the formatting doesn't have errors is included in the
 `meson test -C build/ github-pages` run as part of the CI.
 
-## Man pages
+### Man pages
 
 Manpages for binaries and libraries, and the DBUS interfaces, can be found under
 `man/` and should ideally be kept in sync with changes to the corresponding
 binaries and libraries.
 
-## Translations
+### Translations
 
 Translations files for binaries and daemons, provided by volunteers, can be found
 under `po/` in the usual format. They are kept up to date by contributors and by
 automated tools.
 
-# System Configuration files and presets
+## System Configuration files and presets
 
 Presets (or templates from which they are generated) for various daemons and tools
 can be found under various directories such as `factory/`, `modprobe.d/`, `network/`,
 `presets/`, `rules.d/`, `shell-completion/`, `sysctl.d/`, `sysusers.d/`, `tmpfiles.d/`.
 
-# Utilities for Developers
+## Utilities for Developers
 
 `tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various
 utilities and scripts that are used by maintainers and developers. They are not
diff --git a/docs/HACKING.md b/docs/HACKING.md
index 3f6838cfd0..9d938769ab 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -331,7 +331,7 @@ debug and set "processId" to "${command:pickProcess}". Now, when starting the de
 the PID of the process you want to debug. Run `systemctl show --property MainPID --value ` in the
 container to figure out the PID and enter it when asked and VSCode will attach to that process instead.
 
-# Debugging systemd-boot
+## Debugging systemd-boot
 
 During boot, systemd-boot and the stub loader will output a message like `systemd-boot@0x0A,0x0B`,
 providing the location of the text and data sections. These location can then be used to attach
diff --git a/docs/RESOLVED-VPNS.md b/docs/RESOLVED-VPNS.md
index e06fbc3d2f..97c1125242 100644
--- a/docs/RESOLVED-VPNS.md
+++ b/docs/RESOLVED-VPNS.md
@@ -112,7 +112,7 @@ and another one with `~corp.company.example` — both suffixes match a lookup fo
 `foo.corp.company.example`, but the latter interface wins, since the match is
 for four labels, while the other is for zero labels.
 
-# Putting it Together
+## Putting it Together
 
 Let's discuss how the three DNS routing concepts above are best used for a
 reasonably complex scenario consisting of:
@@ -159,7 +159,7 @@ else.  If `privacy0` is then downed again, `wifi0` will get the regular DNS
 traffic again, and `company0` will still get the company's internal domain and
 IP subnet traffic and nothing else. Everything hence works as intended.
 
-# How to Implement this in Your VPN Software
+## How to Implement this in Your VPN Software
 
 Most likely you want to expose a boolean in some way that declares whether a
 specific VPN is of the *corporate* or the *privacy* kind:
@@ -177,7 +177,7 @@ specific VPN is of the *corporate* or the *privacy* kind:
 traditional, i.e. with any search domains as acquired, do not set `~.` though,
 and do not disable `default-route`.)
 
-# The APIs
+## The APIs
 
 Now we determined how we want to configure things, but how do you actually get
 the configuration to `systemd-resolved.service`? There are three relevant
@@ -222,7 +222,7 @@ interfaces:
    propagate the `default-route` boolean, nor can be used to configure the
    `~….in-addr.arpa` or `~.ip6.arpa` routing domains.
 
-# Ordering
+## Ordering
 
 When configuring per-interface DNS configuration settings it is wise to
 configure everything *before* actually upping the interface. Once the interface
@@ -235,7 +235,7 @@ as the former without the latter has no effect, but the latter without the
 former will result in DNS traffic possibly being generated, in a non-desirable
 way given that the routing information is not set yet.
 
-# Downgrading Search Domains to Routing Domains
+## Downgrading Search Domains to Routing Domains
 
 Many VPN implementations provide a way how VPN servers can inform VPN clients
 about search domains to use. In some cases it might make sense to install those

From 62bbb96d0070ea3a2097ebc350ffadc9752eee55 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 19:05:29 +0200
Subject: [PATCH 14/16] docs: regenerate highlight style and streamline
 background overwrite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

 * Update to rougify 3.26.1 styling
 * Adapt background overwrite by removing default background color
   and only adding explicit overwrites for syntax error
   (error stylings appear for example in json-excerpts –
   see HACKING.md – and are therefore hidden by our css)
---
 docs/style.css | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/style.css b/docs/style.css
index fc2bd1c774..9393ee0a9b 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -128,7 +128,8 @@ tbody td {
   vertical-align: top;
 }
 
-/* Github Code Highlighting */
+/* Rouge Code Highlight, github style */
+/* Generated with: rougify style github | sed '/background-color: #f8f8f8/d' */
 .highlight table td { padding: 5px; }
 .highlight table pre { margin: 0; }
 .highlight .cm {
@@ -235,6 +236,10 @@ tbody td {
 .highlight .m, .highlight .mb, .highlight .mx {
   color: #009999;
 }
+.highlight .sa {
+  color: #000000;
+  font-weight: bold;
+}
 .highlight .sb {
   color: #d14;
 }
@@ -268,7 +273,7 @@ tbody td {
 .highlight .ss {
   color: #990073;
 }
-.highlight .s, .highlight .sa, .highlight .dl {
+.highlight .s, .highlight .dl {
   color: #d14;
 }
 .highlight .na {
@@ -335,9 +340,6 @@ tbody td {
 .highlight .w {
   color: #bbbbbb;
 }
-.highlight {
-  background-color: #f8f8f8;
-}
 
 
 /* Code Blocks */
@@ -348,8 +350,9 @@ tbody td {
 
   overflow: auto;
 }
-.highlighter-rouge * {
-  background-color: white;
+.highlighter-rouge .highlight .err {
+  background: transparent !important;
+  color: inherit !important;
 }
 
 /* Inline Code */

From 9b266e4349826140c41e965216835bae745e3db1 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 10:38:07 +0200
Subject: [PATCH 15/16] docs: add dark mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Respect the user agent property  `prefers-color-scheme` by
rendering the documentation in dark mode, if requested.

Reorganise CSS to store the color palette into CSS variables
and reference these from another set of CSS variables that
are dynamically switched based on the prefers-color-scheme
media query.

Light mode variables stay they same as before,
but to ease color mixing, the current RGB values
have been transformed to HSL (using chrome devtools).
The current body background is now --sd-gray-extralight,
the current body color is now --sd-gray-extradark.
Other gray-variations, needed for dark-mode constrasts
are derived from these colors using HSL lightness shifting.

The systemd brand black color is used as dark mode background
and a matching extralight gray font color has been selected.

The link font-weight is reduced to 400 in dark mode,
as the green color on dark ground becomes to overwhelming
with a bold font.

The systemd logo color is dynamically swapped by using
the special fill value `currentColor` for dark/light-mode
depending parts – as per specification on brand.systemd.io
---
 docs/_includes/header.html                    |   4 +-
 .../{page-logo.svg => systemd-logo.svg}       |   6 +-
 docs/style.css                                | 574 +++++++++++-------
 3 files changed, 361 insertions(+), 223 deletions(-)
 rename docs/assets/{page-logo.svg => systemd-logo.svg} (93%)

diff --git a/docs/_includes/header.html b/docs/_includes/header.html
index 341971df70..4f2f73b142 100644
--- a/docs/_includes/header.html
+++ b/docs/_includes/header.html
@@ -5,7 +5,9 @@
   

 
     
 
   

diff --git a/docs/assets/page-logo.svg b/docs/assets/systemd-logo.svg
similarity index 93%
rename from docs/assets/page-logo.svg
rename to docs/assets/systemd-logo.svg
index 0adf1ea478..a8af438dca 100644
--- a/docs/assets/page-logo.svg
+++ b/docs/assets/systemd-logo.svg
@@ -1,7 +1,7 @@
-
+
diff --git a/docs/style.css b/docs/style.css
index 9393ee0a9b..74673bc93f 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -12,6 +12,52 @@
     font-weight: 600;
 }
 
+/* Variables */
+:root {
+  --sd-brand-black: hsl(270, 19%, 13%); /* #201A26; */
+  --sd-brand-green: hsl(145, 66%, 51%); /* #30D475; */
+  --sd-brand-white: #fff;
+
+  --sd-green: hsl(145, 66%, 43%); /* #26b763 */
+  --sd-gray-extralight: hsl(30, 10%, 96%); /* #f6f5f4 */
+  --sd-gray-light: hsl(30, 10%, 92%);
+  --sd-gray: hsl(30, 10%, 85%);
+  --sd-gray-dark: hsl(257, 23%, 20%);
+  --sd-gray-extradark: hsl(257, 23%, 16%); /* #241f31 */
+
+  --sd-highlight-bg-light: rgba(255, 255, 255, 1);
+  --sd-highlight-bg-dark: rgba(0, 0, 0, .6);
+  --sd-highlight-inline-bg-light: rgba(0, 0, 0, 0.07);
+  --sd-highlight-inline-bg-dark: rgba(255, 255, 255, 0.1);
+
+  --sd-font-weight-normal: 400;
+  --sd-font-weight-bold: 600;
+
+  /* Light mode variables */
+  --sd-foreground-color: var(--sd-gray-extradark);
+  --sd-background-color: var(--sd-gray-extralight);
+  --sd-logo-color: var(--sd-brand-black);
+  --sd-link-color: var(--sd-green);
+  --sd-small-color: var(--sd-gray-dark);
+  --sd-highlight-bg: var(--sd-highlight-bg-light);
+  --sd-highlight-inline-bg: var(--sd-highlight-inline-bg-light);
+  --sd-link-font-weight: var(--sd-font-weight-bold);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    color-scheme: dark;
+    --sd-foreground-color: var(--sd-gray);
+    --sd-background-color: var(--sd-brand-black);
+    --sd-logo-color: var(--sd-brand-white);
+    --sd-link-color: var(--sd-brand-green);
+    --sd-small-color: var(--sd-gray);
+    --sd-highlight-bg: var(--sd-highlight-bg-dark);
+    --sd-highlight-inline-bg: var(--sd-highlight-inline-bg-dark);
+    --sd-link-font-weight: var(--sd-font-weight-normal);
+  }
+}
+
 /* Typography */
 * {
   -moz-box-sizing: border-box;
@@ -27,8 +73,8 @@ html, body {
   line-height: 1.6;
 }
 body {
-  color: #241f31;
-  background-color: #f6f5f4;
+  color: var(--sd-foreground-color);
+  background-color: var(--sd-background-color);
 }
 h1, h2, h3, h4, h5, h6 {
   margin: 1rem 0 0.625rem;
@@ -57,9 +103,9 @@ h3 {
   font-size: 1.15rem;
 }
 a {
-  font-weight: 600;
+  font-weight: var(--sd-link-font-weight);
   text-decoration: none;
-  color: #26b763;
+  color: var(--sd-link-color);
   cursor: pointer;
 }
 a:hover {
@@ -69,7 +115,7 @@ b {
   font-weight: 600;
 }
 small {
-  color: #777;
+  color: var(--sd-small-color);
 }
 hr {
   margin: 3rem auto 4rem;
@@ -89,8 +135,9 @@ hr {
 .page-logo {
   display: block;
   padding: 5rem 0 3rem;
+  color: var(--sd-logo-color);
 }
-.page-logo > img {
+.page-logo > svg {
   display: block;
   width: 12.625em;
   height: auto;
@@ -98,16 +145,16 @@ hr {
 }
 
 .brand-white {
-  background-color: #fff;
+  background-color: var(--sd-brand-white);
 }
 
 .brand-green {
-  background-color: #30D475;
+  background-color: var(--sd-brand-green);
 }
 
 .brand-black {
-  background-color: #201A26;
-  color: white;
+  background-color: var(--sd-brand-black);
+  color: var(--sd-white);
 }
 
 .page-link::after {
@@ -132,221 +179,306 @@ tbody td {
 /* Generated with: rougify style github | sed '/background-color: #f8f8f8/d' */
 .highlight table td { padding: 5px; }
 .highlight table pre { margin: 0; }
-.highlight .cm {
-  color: #999988;
-  font-style: italic;
-}
-.highlight .cp {
-  color: #999999;
-  font-weight: bold;
-}
-.highlight .c1 {
-  color: #999988;
-  font-style: italic;
-}
-.highlight .cs {
-  color: #999999;
-  font-weight: bold;
-  font-style: italic;
-}
-.highlight .c, .highlight .ch, .highlight .cd, .highlight .cpf {
-  color: #999988;
-  font-style: italic;
-}
-.highlight .err {
-  color: #a61717;
-  background-color: #e3d2d2;
-}
-.highlight .gd {
-  color: #000000;
-  background-color: #ffdddd;
-}
-.highlight .ge {
-  color: #000000;
-  font-style: italic;
-}
-.highlight .gr {
-  color: #aa0000;
-}
-.highlight .gh {
-  color: #999999;
-}
-.highlight .gi {
-  color: #000000;
-  background-color: #ddffdd;
-}
-.highlight .go {
-  color: #888888;
-}
-.highlight .gp {
-  color: #555555;
-}
-.highlight .gs {
-  font-weight: bold;
-}
-.highlight .gu {
-  color: #aaaaaa;
-}
-.highlight .gt {
-  color: #aa0000;
-}
-.highlight .kc {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .kd {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .kn {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .kp {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .kr {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .kt {
-  color: #445588;
-  font-weight: bold;
-}
-.highlight .k, .highlight .kv {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .mf {
-  color: #009999;
-}
-.highlight .mh {
-  color: #009999;
-}
-.highlight .il {
-  color: #009999;
-}
-.highlight .mi {
-  color: #009999;
-}
-.highlight .mo {
-  color: #009999;
-}
-.highlight .m, .highlight .mb, .highlight .mx {
-  color: #009999;
-}
-.highlight .sa {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .sb {
-  color: #d14;
-}
-.highlight .sc {
-  color: #d14;
-}
-.highlight .sd {
-  color: #d14;
-}
-.highlight .s2 {
-  color: #d14;
-}
-.highlight .se {
-  color: #d14;
-}
-.highlight .sh {
-  color: #d14;
-}
-.highlight .si {
-  color: #d14;
-}
-.highlight .sx {
-  color: #d14;
-}
-.highlight .sr {
-  color: #009926;
-}
-.highlight .s1 {
-  color: #d14;
-}
-.highlight .ss {
-  color: #990073;
-}
-.highlight .s, .highlight .dl {
-  color: #d14;
-}
-.highlight .na {
-  color: #008080;
-}
-.highlight .bp {
-  color: #999999;
-}
-.highlight .nb {
-  color: #0086B3;
-}
-.highlight .nc {
-  color: #445588;
-  font-weight: bold;
-}
-.highlight .no {
-  color: #008080;
-}
-.highlight .nd {
-  color: #3c5d5d;
-  font-weight: bold;
-}
-.highlight .ni {
-  color: #800080;
-}
-.highlight .ne {
-  color: #990000;
-  font-weight: bold;
-}
-.highlight .nf, .highlight .fm {
-  color: #990000;
-  font-weight: bold;
-}
-.highlight .nl {
-  color: #990000;
-  font-weight: bold;
-}
-.highlight .nn {
-  color: #555555;
-}
-.highlight .nt {
-  color: #000080;
-}
-.highlight .vc {
-  color: #008080;
-}
-.highlight .vg {
-  color: #008080;
-}
-.highlight .vi {
-  color: #008080;
-}
-.highlight .nv, .highlight .vm {
-  color: #008080;
-}
-.highlight .ow {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .o {
-  color: #000000;
-  font-weight: bold;
-}
-.highlight .w {
-  color: #bbbbbb;
+
+@media (prefers-color-scheme: light) {
+  .highlight .cm {
+    color: #999988;
+    font-style: italic;
+  }
+  .highlight .cp {
+    color: #999999;
+    font-weight: bold;
+  }
+  .highlight .c1 {
+    color: #999988;
+    font-style: italic;
+  }
+  .highlight .cs {
+    color: #999999;
+    font-weight: bold;
+    font-style: italic;
+  }
+  .highlight .c, .highlight .ch, .highlight .cd, .highlight .cpf {
+    color: #999988;
+    font-style: italic;
+  }
+  .highlight .err {
+    color: #a61717;
+    background-color: #e3d2d2;
+  }
+  .highlight .gd {
+    color: #000000;
+    background-color: #ffdddd;
+  }
+  .highlight .ge {
+    color: #000000;
+    font-style: italic;
+  }
+  .highlight .gr {
+    color: #aa0000;
+  }
+  .highlight .gh {
+    color: #999999;
+  }
+  .highlight .gi {
+    color: #000000;
+    background-color: #ddffdd;
+  }
+  .highlight .go {
+    color: #888888;
+  }
+  .highlight .gp {
+    color: #555555;
+  }
+  .highlight .gs {
+    font-weight: bold;
+  }
+  .highlight .gu {
+    color: #aaaaaa;
+  }
+  .highlight .gt {
+    color: #aa0000;
+  }
+  .highlight .kc {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .kd {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .kn {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .kp {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .kr {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .kt {
+    color: #445588;
+    font-weight: bold;
+  }
+  .highlight .k, .highlight .kv {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .mf {
+    color: #009999;
+  }
+  .highlight .mh {
+    color: #009999;
+  }
+  .highlight .il {
+    color: #009999;
+  }
+  .highlight .mi {
+    color: #009999;
+  }
+  .highlight .mo {
+    color: #009999;
+  }
+  .highlight .m, .highlight .mb, .highlight .mx {
+    color: #009999;
+  }
+  .highlight .sa {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .sb {
+    color: #d14;
+  }
+  .highlight .sc {
+    color: #d14;
+  }
+  .highlight .sd {
+    color: #d14;
+  }
+  .highlight .s2 {
+    color: #d14;
+  }
+  .highlight .se {
+    color: #d14;
+  }
+  .highlight .sh {
+    color: #d14;
+  }
+  .highlight .si {
+    color: #d14;
+  }
+  .highlight .sx {
+    color: #d14;
+  }
+  .highlight .sr {
+    color: #009926;
+  }
+  .highlight .s1 {
+    color: #d14;
+  }
+  .highlight .ss {
+    color: #990073;
+  }
+  .highlight .s, .highlight .dl {
+    color: #d14;
+  }
+  .highlight .na {
+    color: #008080;
+  }
+  .highlight .bp {
+    color: #999999;
+  }
+  .highlight .nb {
+    color: #0086B3;
+  }
+  .highlight .nc {
+    color: #445588;
+    font-weight: bold;
+  }
+  .highlight .no {
+    color: #008080;
+  }
+  .highlight .nd {
+    color: #3c5d5d;
+    font-weight: bold;
+  }
+  .highlight .ni {
+    color: #800080;
+  }
+  .highlight .ne {
+    color: #990000;
+    font-weight: bold;
+  }
+  .highlight .nf, .highlight .fm {
+    color: #990000;
+    font-weight: bold;
+  }
+  .highlight .nl {
+    color: #990000;
+    font-weight: bold;
+  }
+  .highlight .nn {
+    color: #555555;
+  }
+  .highlight .nt {
+    color: #000080;
+  }
+  .highlight .vc {
+    color: #008080;
+  }
+  .highlight .vg {
+    color: #008080;
+  }
+  .highlight .vi {
+    color: #008080;
+  }
+  .highlight .nv, .highlight .vm {
+    color: #008080;
+  }
+  .highlight .ow {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .o {
+    color: #000000;
+    font-weight: bold;
+  }
+  .highlight .w {
+    color: #bbbbbb;
+  }
 }
 
+@media (prefers-color-scheme: dark) {
+  /* rouge "base16.dark" code highlight */
+  /* generated with: rougify style base16.dark | sed '/background-color: #151515/d' */
+  .highlight, .highlight .w {
+    color: #d0d0d0;
+  }
+  .highlight .err {
+    color: #151515;
+    background-color: #ac4142;
+  }
+  .highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cpf, .highlight .c1, .highlight .cs {
+    color: #505050;
+  }
+  .highlight .cp {
+    color: #f4bf75;
+  }
+  .highlight .nt {
+    color: #f4bf75;
+  }
+  .highlight .o, .highlight .ow {
+    color: #d0d0d0;
+  }
+  .highlight .p, .highlight .pi {
+    color: #d0d0d0;
+  }
+  .highlight .gi {
+    color: #90a959;
+  }
+  .highlight .gd {
+    color: #ac4142;
+  }
+  .highlight .gh {
+    color: #6a9fb5;
+    font-weight: bold;
+  }
+  .highlight .k, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kv {
+    color: #aa759f;
+  }
+  .highlight .kc {
+    color: #d28445;
+  }
+  .highlight .kt {
+    color: #d28445;
+  }
+  .highlight .kd {
+    color: #d28445;
+  }
+  .highlight .s, .highlight .sb, .highlight .sc, .highlight .dl, .highlight .sd, .highlight .s2, .highlight .sh, .highlight .sx, .highlight .s1 {
+    color: #90a959;
+  }
+  .highlight .sa {
+    color: #aa759f;
+  }
+  .highlight .sr {
+    color: #75b5aa;
+  }
+  .highlight .si {
+    color: #8f5536;
+  }
+  .highlight .se {
+    color: #8f5536;
+  }
+  .highlight .nn {
+    color: #f4bf75;
+  }
+  .highlight .nc {
+    color: #f4bf75;
+  }
+  .highlight .no {
+    color: #f4bf75;
+  }
+  .highlight .na {
+    color: #6a9fb5;
+  }
+  .highlight .m, .highlight .mb, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mx {
+    color: #90a959;
+  }
+  .highlight .ss {
+    color: #90a959;
+  }
+}
 
 /* Code Blocks */
 .highlighter-rouge {
   padding: 2px 1rem;
   border-radius: 5px;
-  background-color: white;
+  color: var(--sd-foreground-color);
+  background-color: var(--sd-highlight-bg);
 
   overflow: auto;
 }
@@ -358,5 +490,9 @@ tbody td {
 /* Inline Code */
 code.highlighter-rouge {
   padding: 2px 6px;
-  background-color: rgba(0,0,0, 0.07);
+  background-color: var(--sd-highlight-inline-bg);
+}
+
+a code.highlighter-rouge {
+  color: inherit;
 }

From 2eca6d602f8ea9c8e05490ef385e22db54140801 Mon Sep 17 00:00:00 2001
From: Benjamin Franzke 
Date: Tue, 17 May 2022 13:48:27 +0200
Subject: [PATCH 16/16] docs: overhaul styling for example log messages on
 startpage

 * Use brand-green for demo log messages on the startpage
   instead of the default `green` color defined by the browser vendor
   (after all, the brand green color is intended to reflect the
   boot status output)
 * Add a matching blue intro color (mixed using HSL from brand-green
   by 55deg hue rotation and 4% lightness)
 * Use a defined font-size
   (to avoid blurry rendering at 13.33333px, due to font-size: smaller)
 * Add possibility for the browser to show horizontal scrollbar
   (avoid overflow in mobile view)
---
 docs/index.md  | 78 +++++++++++++++++++++++++-------------------------
 docs/style.css | 25 +++++++++++++++-
 2 files changed, 63 insertions(+), 40 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index a4577093d6..1b4863088c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -33,63 +33,63 @@ Other parts include a logging daemon, utilities to control basic system configur
 
 ---
 
-
-Welcome to Fedora 20 (Heisenbug)!
+
+Welcome to Fedora 20 (Heisenbug)!
 
-[  OK  ] Reached target Remote File Systems.
-[  OK  ] Listening on Delayed Shutdown Socket.
-[  OK  ] Listening on /dev/initctl Compatibility Named Pipe.
-[  OK  ] Reached target Paths.
-[  OK  ] Reached target Encrypted Volumes.
-[  OK  ] Listening on Journal Socket.
+[  OK  ] Reached target Remote File Systems.
+[  OK  ] Listening on Delayed Shutdown Socket.
+[  OK  ] Listening on /dev/initctl Compatibility Named Pipe.
+[  OK  ] Reached target Paths.
+[  OK  ] Reached target Encrypted Volumes.
+[  OK  ] Listening on Journal Socket.
          Mounting Huge Pages File System...
          Mounting POSIX Message Queue File System...
          Mounting Debug File System...
          Starting Journal Service...
-[  OK  ] Started Journal Service.
+[  OK  ] Started Journal Service.
          Mounting Configuration File System...
          Mounting FUSE Control File System...
-[  OK  ] Created slice Root Slice.
-[  OK  ] Created slice User and Session Slice.
-[  OK  ] Created slice System Slice.
-[  OK  ] Reached target Slices.
-[  OK  ] Reached target Swap.
+[  OK  ] Created slice Root Slice.
+[  OK  ] Created slice User and Session Slice.
+[  OK  ] Created slice System Slice.
+[  OK  ] Reached target Slices.
+[  OK  ] Reached target Swap.
          Mounting Temporary Directory...
-[  OK  ] Reached target Local File Systems (Pre).
+[  OK  ] Reached target Local File Systems (Pre).
          Starting Load Random Seed...
          Starting Load/Save Random Seed...
-[  OK  ] Mounted Huge Pages File System.
-[  OK  ] Mounted POSIX Message Queue File System.
-[  OK  ] Mounted Debug File System.
-[  OK  ] Mounted Configuration File System.
-[  OK  ] Mounted FUSE Control File System.
-[  OK  ] Mounted Temporary Directory.
-[  OK  ] Started Load Random Seed.
-[  OK  ] Started Load/Save Random Seed.
-[  OK  ] Reached target Local File Systems.
+[  OK  ] Mounted Huge Pages File System.
+[  OK  ] Mounted POSIX Message Queue File System.
+[  OK  ] Mounted Debug File System.
+[  OK  ] Mounted Configuration File System.
+[  OK  ] Mounted FUSE Control File System.
+[  OK  ] Mounted Temporary Directory.
+[  OK  ] Started Load Random Seed.
+[  OK  ] Started Load/Save Random Seed.
+[  OK  ] Reached target Local File Systems.
          Starting Recreate Volatile Files and Directories...
          Starting Trigger Flushing of Journal to Persistent Storage...
-[  OK  ] Started Recreate Volatile Files and Directories.
+[  OK  ] Started Recreate Volatile Files and Directories.
          Starting Record System Reboot/Shutdown in UTMP...
-[  OK  ] Started Trigger Flushing of Journal to Persistent Storage.
-[  OK  ] Started Record System Reboot/Shutdown in UTMP.
-[  OK  ] Reached target System Initialization.
-[  OK  ] Reached target Timers.
-[  OK  ] Listening on D-Bus System Message Bus Socket.
-[  OK  ] Reached target Sockets.
-[  OK  ] Reached target Basic System.
+[  OK  ] Started Trigger Flushing of Journal to Persistent Storage.
+[  OK  ] Started Record System Reboot/Shutdown in UTMP.
+[  OK  ] Reached target System Initialization.
+[  OK  ] Reached target Timers.
+[  OK  ] Listening on D-Bus System Message Bus Socket.
+[  OK  ] Reached target Sockets.
+[  OK  ] Reached target Basic System.
          Starting Permit User Sessions...
          Starting D-Bus System Message Bus...
-[  OK  ] Started D-Bus System Message Bus.
+[  OK  ] Started D-Bus System Message Bus.
          Starting Login Service...
          Starting Cleanup of Temporary Directories...
-[  OK  ] Started Permit User Sessions.
-[  OK  ] Started Cleanup of Temporary Directories.
+[  OK  ] Started Permit User Sessions.
+[  OK  ] Started Cleanup of Temporary Directories.
          Starting Console Getty...
-[  OK  ] Started Console Getty.
-[  OK  ] Reached target Login Prompts.
-[  OK  ] Started Login Service.
-[  OK  ] Reached target Multi-User System.
+[  OK  ] Started Console Getty.
+[  OK  ] Reached target Login Prompts.
+[  OK  ] Started Login Service.
+[  OK  ] Reached target Multi-User System.
 
 Fedora release 20 (Heisenbug)
 Kernel 3.9.2-200.fc18.x86_64 on an x86_64 (console)
diff --git a/docs/style.css b/docs/style.css
index 74673bc93f..112e5457c8 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -24,6 +24,7 @@
   --sd-gray: hsl(30, 10%, 85%);
   --sd-gray-dark: hsl(257, 23%, 20%);
   --sd-gray-extradark: hsl(257, 23%, 16%); /* #241f31 */
+  --sd-blue: hsl(200, 66%, 55%);
 
   --sd-highlight-bg-light: rgba(255, 255, 255, 1);
   --sd-highlight-bg-dark: rgba(0, 0, 0, .6);
@@ -131,6 +132,20 @@ hr {
   max-width: 720px;
 }
 
+/* Custom content */
+.intro-code-block {
+  background-color: var(--sd-brand-black);
+  color: var(--sd-brand-white);
+  font-size: 0.875rem;
+  padding: 1em;
+  overflow-x: auto;
+}
+@media (prefers-color-scheme: dark) {
+  .intro-code-block {
+    background-color: var(--sd-highlight-bg);
+  }
+}
+
 /* Singletons */
 .page-logo {
   display: block;
@@ -154,7 +169,15 @@ hr {
 
 .brand-black {
   background-color: var(--sd-brand-black);
-  color: var(--sd-white);
+  color: var(--sd-brand-white);
+}
+
+.color-green {
+  color: var(--sd-brand-green);
+}
+
+.color-blue {
+  color: var(--sd-blue);
 }
 
 .page-link::after {