[PR PATCH] [RFC] Create a version of Manual.md in mdBook

[classabbyamp <classabbyamp@users.noreply.github.com>]

[-- Attachment #1: Type: text/plain, Size: 1092 bytes --]

There is a new pull request by classabbyamp against master on the void-packages repository

https://github.com/classabbyamp/void-packages manual-mdbook
https://github.com/void-linux/void-packages/pull/35856

[RFC] Create a version of Manual.md in mdBook
This idea was mentioned once on IRC, so I thought I might take a stab at it and submit it for discussion.

I set out to create a version of `Manual.md` that is a bit more user/noob-friendly than a giant monolith of a document, while still preserving the workflow surrounding it. Thus, I created a mdBook pre-processor that processes Manual.md and builds the book, without the need for converting Manual.md *into* an mdBook.

A live example of what is currently generated by mdBook is available here: https://book.qrm.cat/

Note that this is not fully complete, but is a decent working prototype. There is still a little work to be done to set up some CI to check and deploy the generated book, as well as some tweaks in the area of theming.

A patch file from https://github.com/void-linux/void-packages/pull/35856.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-manual-mdbook-35856.patch --]
[-- Type: text/x-diff, Size: 32936 bytes --]

From c5c39afae060aa8d4e2dfb17c369eaf3828c4ed8 Mon Sep 17 00:00:00 2001
From: classabbyamp <dev@kb6.ee>
Date: Fri, 25 Feb 2022 21:35:29 -0500
Subject: [PATCH 1/2] Manual.md: make heading levels match Table of Contents

---
 Manual.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Manual.md b/Manual.md
index 40b2321f7a25..5cb2e1d6c1f2 100644
--- a/Manual.md
+++ b/Manual.md
@@ -814,10 +814,10 @@ not a particular package is present in `makedepends` or `hostmakedepends`, that
 package shouldn't be added as a build time dependency.
 
 <a id="repositories"></a>
-#### Repositories
+### Repositories
 
 <a id="repo_by_branch"></a>
-##### Repositories defined by Branch
+#### Repositories defined by Branch
 
 The global repository takes the name of
 the current branch, except if the name of the branch is master. Then the resulting
@@ -825,7 +825,7 @@ repository will be at the global scope. The usage scenario is that the user can
 update multiple packages in a second branch without polluting his local repository.
 
 <a id="pkg_defined_repo"></a>
-##### Package defined Repositories
+#### Package defined Repositories
 
 The second way to define a repository is by setting the `repository` variable in
 a template. This way the maintainer can define repositories for a specific
@@ -1909,7 +1909,7 @@ If it is running under another architecture it tries to use the host's `install-
 utility.
 
 <a id="triggers_initramfs_regenerate"></a>
-### initramfs-regenerate
+#### initramfs-regenerate
 
 The initramfs-regenerate trigger will trigger the regeneration of all kernel
 initramfs images after package installation or removal. The trigger must be

From 322e4fe5cb1dce4a3700c9991abcd1a36e1e633a Mon Sep 17 00:00:00 2001
From: classabbyamp <dev@kb6.ee>
Date: Fri, 25 Feb 2022 21:36:12 -0500
Subject: [PATCH 2/2] manual/: Add script to generate mdbook of Manual.md

---
 .gitignore                       |   1 +
 manual/book.toml                 |  13 +
 manual/generate_mdbook.py        | 104 ++++++++
 manual/src/SUMMARY.md            |   1 +
 manual/src/theme/book.js         | 104 ++++++++
 manual/src/theme/css/general.css | 419 +++++++++++++++++++++++++++++++
 manual/src/theme/css/print.css   |  54 ++++
 manual/src/theme/favicon.png     | Bin 0 -> 5800 bytes
 manual/src/theme/index.hbs       | 157 ++++++++++++
 9 files changed, 853 insertions(+)
 create mode 100644 manual/book.toml
 create mode 100644 manual/generate_mdbook.py
 create mode 100644 manual/src/SUMMARY.md
 create mode 100644 manual/src/theme/book.js
 create mode 100644 manual/src/theme/css/general.css
 create mode 100644 manual/src/theme/css/print.css
 create mode 100644 manual/src/theme/favicon.png
 create mode 100644 manual/src/theme/index.hbs

diff --git a/.gitignore b/.gitignore
index 958f644eee94..52806ca91964 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,4 @@ etc/conf.*
 etc/virtual
 etc/xbps.d/custom
 .xbps-checkvers*.plist
+/manual/book/
diff --git a/manual/book.toml b/manual/book.toml
new file mode 100644
index 000000000000..5ef5064d8928
--- /dev/null
+++ b/manual/book.toml
@@ -0,0 +1,13 @@
+[book]
+authors = ["The Void Linux Team"]
+multilingual = false
+src = "src"
+title = "XBPS Source Packages Manual"
+
+[preprocessor.gen_manual]
+command = "python3 generate_mdbook.py"
+
+[output.html]
+# TODO: this should be a submodule or something
+# to avoid de-syncing with void-docs/src/theme
+theme = "src/theme"
diff --git a/manual/generate_mdbook.py b/manual/generate_mdbook.py
new file mode 100644
index 000000000000..2e77c40f55b1
--- /dev/null
+++ b/manual/generate_mdbook.py
@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+
+from dataclasses import asdict, dataclass, field
+import json
+from pathlib import Path
+import re
+import sys
+from typing import Optional
+
+
+HEADING_RE = re.compile(r"###? (?:\w|\d)")
+ANCHOR_RE = re.compile(r'<a id=".+"></a>')
+
+
+@dataclass
+class Chapter:
+    name: str
+    content: str
+    path: str
+    source_path: str
+    number: Optional[list[int]] = None
+    sub_items: list['Chapter'] = field(default_factory=list)
+    parent_names: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Section:
+    Chapter: Chapter
+
+
+@dataclass
+class Book:
+    sections: list[Section]
+
+
+def slugify(s: str) -> str:
+    return s.lower().replace(" ", "-").replace(".", "-").replace("`", "")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "supports":
+            raise SystemExit
+
+    manual = Path("../Manual.md").read_text().split("\n")
+
+    sections = []
+    curr_chapter = []
+    hlevel = None
+    heading = None
+    fn = None
+    in_section = False
+
+    for line in manual:
+        if HEADING_RE.match(line):
+            if in_section:
+                if ANCHOR_RE.search(curr_chapter[-1]):
+                    del curr_chapter[-1]
+
+                sections.append(
+                    Section(
+                        Chapter(
+                            name=heading,
+                            number=num,
+                            content="\n".join(curr_chapter),
+                            path=fn,
+                            source_path=fn,
+                        )
+                    )
+                )
+            curr_chapter = ["#" + line.lstrip("#")]
+            hlevel, heading = line.split(" ", maxsplit=1)
+            fn = f"./{slugify(heading)}.md"
+
+            match len(hlevel):
+                # intro/help
+                case 2:
+                    num = None
+                # other "top" level headings
+                case 3:
+                    num = [ len(sections) ]
+                case _:
+                    continue
+
+            in_section = True
+        elif in_section:
+            curr_chapter.append(line.replace("####", "##", 1))
+
+    # get the last section
+    sections.append(
+        Section(
+            Chapter(
+                name=heading,
+                number=num,
+                content="\n".join(curr_chapter),
+                path=fn,
+                source_path=fn,
+            )
+        )
+    )
+
+    # mdBook requires this key in the emitted json, for reasons unknown
+    book = asdict(Book(sections)) | {"__non_exhaustive": None}
+    print(json.dumps(book))
diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
new file mode 100644
index 000000000000..73fa82d6e79c
--- /dev/null
+++ b/manual/src/SUMMARY.md
@@ -0,0 +1 @@
+<!-- leave this file empty. mdBook needs it but it will not be used -->
diff --git a/manual/src/theme/book.js b/manual/src/theme/book.js
new file mode 100644
index 000000000000..853247bfc4c9
--- /dev/null
+++ b/manual/src/theme/book.js
@@ -0,0 +1,104 @@
+"use strict";
+
+// Fix back button cache problem
+window.onunload = function () { };
+
+(function sidebar() {
+    var html = document.querySelector("html");
+    var sidebar = document.getElementById("sidebar");
+    var sidebarLinks = document.querySelectorAll('#sidebar a');
+    var sidebarToggleButton = document.getElementById("sidebar-toggle");
+    var firstContact = null;
+
+    function showSidebar() {
+        html.classList.remove('sidebar-hidden')
+        html.classList.add('sidebar-visible');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', 0);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', true);
+        sidebar.setAttribute('aria-hidden', false);
+        try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+    }
+
+    function hideSidebar() {
+        html.classList.remove('sidebar-visible')
+        html.classList.add('sidebar-hidden');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', -1);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', false);
+        sidebar.setAttribute('aria-hidden', true);
+        try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+    }
+
+    // Toggle sidebar
+    sidebarToggleButton.addEventListener('click', function sidebarToggle() {
+        if (html.classList.contains("sidebar-hidden")) {
+            showSidebar();
+        } else if (html.classList.contains("sidebar-visible")) {
+            hideSidebar();
+        } else {
+            if (getComputedStyle(sidebar)['transform'] === 'none') {
+                hideSidebar();
+            } else {
+                showSidebar();
+            }
+        }
+    });
+
+    document.addEventListener('touchstart', function (e) {
+        firstContact = {
+            x: e.touches[0].clientX,
+            time: Date.now()
+        };
+    }, { passive: true });
+
+    document.addEventListener('touchmove', function (e) {
+        if (!firstContact)
+            return;
+
+        var curX = e.touches[0].clientX;
+        var xDiff = curX - firstContact.x,
+            tDiff = Date.now() - firstContact.time;
+
+        if (tDiff < 250 && Math.abs(xDiff) >= 150) {
+            if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+                showSidebar();
+            else if (xDiff < 0 && curX < 300)
+                hideSidebar();
+
+            firstContact = null;
+        }
+    }, { passive: true });
+
+    // Scroll sidebar to current active section
+    var activeSection = sidebar.querySelector(".active");
+    if (activeSection) {
+        sidebar.scrollTop = activeSection.offsetTop;
+    }
+})();
+
+(function chapterNavigation() {
+    document.addEventListener('keydown', function (e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (window.search && window.search.hasFocus()) { return; }
+
+        switch (e.key) {
+            case 'ArrowRight':
+                e.preventDefault();
+                var nextButton = document.querySelector('.nav-chapters.next');
+                if (nextButton) {
+                    window.location.href = nextButton.href;
+                }
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                var previousButton = document.querySelector('.nav-chapters.previous');
+                if (previousButton) {
+                    window.location.href = previousButton.href;
+                }
+                break;
+        }
+    });
+})();
diff --git a/manual/src/theme/css/general.css b/manual/src/theme/css/general.css
new file mode 100644
index 000000000000..e0255a8281b1
--- /dev/null
+++ b/manual/src/theme/css/general.css
@@ -0,0 +1,419 @@
+body {
+	font-family: 'Ubuntu', sans-serif;
+	font-size: 1rem;
+	line-height: 1.5;
+	color: #333;
+	margin: 0;
+	background-color: #ffffff;
+}
+h1, h2, h3, h4, h5, h6 { color: #333; }
+a {
+	color: #478061;
+	text-decoration: none;
+}
+a:hover {
+	color: #333;
+	text-decoration: underline;
+}
+
+code {
+	background: #fdf6e3;
+	padding: 2px 4px;
+	border-radius: 4px;
+	white-space: pre-wrap;
+	overflow-wrap: break-word;
+}
+pre code {
+	padding: 0;
+	border-radius: 0;
+}
+pre {
+	padding: .5em;
+	margin: 1em 0;
+	background: #fdf6e3;
+	border: 1px solid #ccc;
+	border-radius: 4px;
+}
+
+blockquote {
+	margin: 20px 0;
+	padding: 0 20px;
+	padding-left: 1em;
+	background: #ebf4ef;
+	border: 1px solid #d1e6da;
+	border-left: none;
+	border-right: none;
+}
+
+li.js-unavailable {
+        background-color: #f6cf68;
+        border-radius: 10px;
+        margin-left: 1em;
+        padding-left: 1em;
+        padding-right: 1em;
+}
+
+table {
+	border-collapse: collapse;
+	display: block;
+	overflow-y: auto;
+}
+table td {
+	padding: 3px 20px;
+	border: 1px #fafafa solid;
+}
+table thead {
+	background: #fafafa;
+}
+table thead td {
+	font-weight: 700;
+	border: none;
+}
+table thead tr {
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+	background: #fafafa;
+}
+
+svg {
+	position: relative;
+	top: .125em;
+	width: 1em;
+	height: auto;
+}
+
+.hidden {
+	display: none;
+}
+
+.icon-button {
+	border: none;
+	background: none;
+	cursor: pointer;
+	padding: 1em;
+}
+
+/* void navigation */
+
+#void-nav {
+	width: 100%;
+	min-height: 50px;
+	background: #478061;
+	font-size: 14px;
+
+	display: flex;
+	flex-direction: row;
+	flex-wrap: wrap;
+}
+#void-nav button,
+#void-nav label {
+	fill: #fff;
+	height: 50px;
+	display: block;
+	line-height: 50px;
+	padding: 0 15px;
+	font-size: 1.2em;
+}
+#void-nav ul {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+}
+
+#void-nav ul#nav-right {
+	margin-left: auto;
+}
+
+#void-nav ul li {
+	display: inline-block;
+}
+#void-nav ul li a {
+	color: #fff;
+	display: block;
+	padding: 0 15px;
+	line-height: 50px;
+	font-size: 1.2em;
+	text-decoration: none
+}
+#void-nav ul li a:hover,
+#void-nav ul li a:focus,
+#void-nav button:hover,
+#void-nav button:focus,
+#void-nav label:hover,
+#void-nav label:focus {
+	background: #000;
+}
+
+#skip-to-content {
+	position: absolute;
+	left: -999px;
+	top: -999px;
+}
+
+#skip-to-content:active,
+#skip-to-content:focus {
+	position: relative;
+	left: 0;
+	top: 0;
+}
+
+/* sidebar  */
+
+.sidebar-hidden #sidebar {
+	display: none;
+}
+#sidebar {
+	padding: .5em;
+	background: #fafafa;
+	font-size: 0.875em;
+}
+#sidebar ol {
+	list-style: none;
+	margin: 0;
+}
+#sidebar ol.chapter {
+	padding: 0;
+	line-height: 2.2em;
+}
+#sidebar ol.section {
+	padding-left: 20px;
+	line-height: 1.9em;
+}
+#sidebar a {
+	color: #000;
+	display: block;
+}
+#sidebar a:hover {
+	color: #478061;
+	text-decoration: none;
+}
+#sidebar a.active {
+	color: #478061;
+}
+
+#sidebar-toggle {
+	display: none;
+}
+
+/* search */
+
+#searchbar {
+	width: 100%;
+	padding: 10px 16px;
+	margin: 5px 0;
+	border-radius: 3px;
+	border: 1px solid #aaa;
+}
+#searchresults-header {
+	font-weight: bold;
+	font-size: 1em;
+	padding: 18px 0 0 5px;
+}
+ul#searchresults {
+	list-style: none;
+	padding-left: 20px;
+}
+ul#searchresults li {
+	margin: 10px 0px;
+	padding: 2px;
+	border-radius: 2px;
+}
+ul#searchresults span.teaser {
+	display: block;
+	clear: both;
+	margin: 5px 0 0 20px;
+	font-size: 0.8em;
+}
+
+/* chapter navigation */
+
+#nav-wide-wrapper {
+	max-width: 800px;
+	margin: 0 auto;
+	margin-top: 50px;
+}
+.previous {
+	float: left;
+}
+.next {
+	float: right;
+	right: 15px;
+}
+.nav-chapters {
+	fill: #ccc;
+	text-align: center;
+	text-decoration: none;
+	display: block;
+	max-width: 150px;
+	min-width: 90px;
+}
+.nav-chapters:hover {
+	text-decoration: none;
+	fill: #333
+}
+
+.nav-chapters svg {
+	margin: 0 auto;
+	width: 1.5em;
+}
+
+/* layout */
+
+body {
+	box-sizing: border-box;
+}
+#content {
+	display: flex;
+	flex-direction: row;
+	width: 100%;
+}
+#page-wrapper {
+	--content-padding: 10px;
+	padding: 0 var(--content-padding);
+	width: calc(100% - var(--content-padding) * 2);
+}
+#search-wrapper,
+#page-wrapper main {
+	width: 100%;
+	max-width: 800px;
+	margin: 0 auto;
+}
+#sidebar {
+	max-width: 300px;
+	flex-shrink: 0;
+}
+
+/* 300px + 800px + 2*90px + 15px */
+@media only screen and (min-width: 1295px) {
+	.sidebar-visible #nav-wide-wrapper {
+		max-width: none;
+		margin: 0;
+	}
+	.sidebar-visible .nav-chapters {
+		background: none;
+		position: fixed;
+		top: 50px;
+		bottom: 0;
+		margin: 0;
+		justify-content: center;
+		align-content: center;
+		display: flex;
+		flex-direction: column;
+	}
+}
+/* 800px + 2*90px + 15px */
+@media only screen and (min-width: 995px) {
+	.sidebar-hidden #nav-wide-wrapper {
+		max-width: none;
+		margin: 0;
+	}
+	.sidebar-hidden .nav-chapters {
+		background: none;
+		position: fixed;
+		top: 50px;
+		bottom: 0;
+		margin: 0;
+		justify-content: center;
+		align-content: center;
+		display: flex;
+		flex-direction: column;
+	}
+	table {
+		display: table;
+	}
+}
+
+@media (prefers-color-scheme: dark) {
+	body {
+		color: #ccc;
+		background-color: #222;
+	}
+	h1, h2, h3, h4, h5, h6 { color: #ccc; }
+	a {
+		color: #62b086;
+	}
+	a:hover {
+		color: #ccc;
+	}
+
+	code {
+		background: inherit;
+	}
+	pre {
+		background: #353535;
+		border: 1px solid #111;
+	}
+
+	blockquote {
+		background: inherit;
+		border-left: .2em solid #ccc;
+		border-right: none;
+		border-top: none;
+		border-bottom: none;
+		padding-top: .5em;
+		padding-bottom: .5em;
+		padding-left: 1em;
+		padding-right: 1em;
+		margin-left: 1em;
+	}
+	blockquote code {
+		color: #62b086;
+	}
+        li.js-unavailable {
+                background-color: #f6cf68;
+                color: #000000;
+                border-radius: 10px;
+                margin-left: 1em;
+                padding-left: 1em;
+                padding-right: 1em;
+        }
+	table td {
+		border: 1px #2c2c2c solid;
+	}
+	table thead {
+		background: #2c2c2c;
+	}
+	table tbody tr:nth-child(2n) {
+		background: #2c2c2c;
+	}
+
+	/* nav */
+	#void-nav ul li a:hover,
+	#void-nav ul li a:focus,
+	#void-nav button:hover,
+	#void-nav button:focus,
+	#void-nav label:hover,
+	#void-nav label:focus {
+		background: #222;
+	}
+
+	#void-nav {
+		background: #295340;
+	}
+
+	/* sidebar  */
+	#sidebar {
+		background: #252525;
+	}
+	#sidebar a {
+		color: #ccc;
+	}
+	#sidebar a:hover {
+		color: #62b086;
+	}
+	#sidebar a.active {
+		color: #62b086;
+	}
+
+	/* search */
+	#searchbar {
+		background-color: #222;
+		color: #ccc;
+	}
+
+	/* chapter navigation */
+	.nav-chapters:hover {
+		fill: #fff
+	}
+}
diff --git a/manual/src/theme/css/print.css b/manual/src/theme/css/print.css
new file mode 100644
index 000000000000..717ccb80ed2c
--- /dev/null
+++ b/manual/src/theme/css/print.css
@@ -0,0 +1,54 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+    display: none;
+}
+
+#page-wrapper.page-wrapper {
+    transform: none;
+    margin-left: 0px;
+    overflow-y: initial;
+}
+
+#content {
+    max-width: none;
+    margin: 0;
+    padding: 0;
+}
+
+.page {
+    overflow-y: initial;
+}
+
+code {
+    background-color: #666666;
+    border-radius: 5px;
+
+    /* Force background to be printed in Chrome */
+    -webkit-print-color-adjust: exact;
+}
+
+pre > .buttons {
+    z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+    color: #4183c4;
+    text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    page-break-inside: avoid;
+    page-break-after: avoid;
+}
+
+pre, code {
+    page-break-inside: avoid;
+    white-space: pre-wrap;
+}
+
+svg {
+    display: none !important;
+}
diff --git a/manual/src/theme/favicon.png b/manual/src/theme/favicon.png
new file mode 100644
index 0000000000000000000000000000000000000000..fd3ec045d08445cdd73c7413e01a89754827593f
GIT binary patch
literal 5800
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

literal 0
HcmV?d00001

diff --git a/manual/src/theme/index.hbs b/manual/src/theme/index.hbs
new file mode 100644
index 000000000000..239c9c5728a1
--- /dev/null
+++ b/manual/src/theme/index.hbs
@@ -0,0 +1,157 @@
+<!DOCTYPE HTML>
+<html lang="{{ language }}" class="sidebar-visible no-js">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="utf-8">
+        <title>{{ title }}</title>
+        <meta name="description" content="{{ description }}">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff" />
+
+        <link rel="shortcut icon" href="{{ path_to_root }}{{ favicon_png }}">
+        <link rel="stylesheet" href="{{ path_to_root }}css/general.css">
+        <link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
+    </head>
+    <body>
+        <!-- Provide site root to javascript -->
+        <script type="text/javascript">
+            var path_to_root = "{{ path_to_root }}";
+        </script>
+		<!-- Work around some values being stored in localStorage wrapped in quotes -->
+		<script type="text/javascript">
+			try {
+				var sidebar = localStorage.getItem('mdbook-sidebar');
+
+				if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+					localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+				}
+			} catch (e) { }
+		</script>
+
+		<header>
+			<nav id="void-nav">
+				<ul>
+					<li><a id="skip-to-content" tabindex="1" href="#main">Skip to content</a></li>
+					<li>
+						<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+							<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
+								<path d="M1 3v2h18V3zm0 8h18V9H1zm0 6h18v-2H1z"/>
+							</svg>
+						</button>
+					</li>
+				{{#if search_enabled}}
+					<li>
+						<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+							<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
+								<path d="M7.5 13c3.04 0 5.5-2.46 5.5-5.5S10.54 2 7.5 2 2 4.46 2 7.5 4.46 13 7.5 13zm4.55.46C10.79 14.43 9.21 15 7.5 15 3.36 15 0 11.64 0 7.5S3.36 0 7.5 0C11.64 0 15 3.36 15 7.5c0 1.71-.57 3.29-1.54 4.55l6.49 6.49-1.41 1.41-6.49-6.49z"/>
+							</svg>
+						</button>
+					</li>
+				{{/if}}
+                                        <noscript>
+                                          <li class="js-unavailable">Search functionality requires JavaScript</li>
+                                        </noscript>
+				</ul>
+				<ul id="nav-right">
+					<li><a href="https://www.voidlinux.org">Home</a></li>
+					<li><a href="https://www.voidlinux.org/news/">News</a></li>
+					<li><a href="https://www.voidlinux.org/download/">Download</a></li>
+					<li><a href="https://www.voidlinux.org/packages/">Packages</a></li>
+					<li><a href="https://docs.voidlinux.org">Documentation</a></li>
+					<li><a href="https://man.voidlinux.org/">Manual Pages</a></li>
+					<li><a href="https://github.com/void-linux">GitHub</a></li>
+				</ul>
+			</nav>
+		</header>
+
+		<div id="content">
+
+			<!-- Hide / unhide sidebar before it is displayed -->
+			<script type="text/javascript">
+				var html = document.querySelector('html');
+				var sidebar = 'hidden';
+				if (document.body.clientWidth >= 1080) {
+					try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+					sidebar = sidebar || 'visible';
+				}
+				html.classList.remove('sidebar-visible');
+				html.classList.add("sidebar-" + sidebar);
+			</script>
+
+			<nav id="sidebar" aria-label="Table of contents">
+				{{#toc}}{{/toc}}
+			</nav>
+
+			<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+			<script type="text/javascript">
+				document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+	document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+	Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+		link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+	});
+			</script>
+
+			<div id="page-wrapper">
+				{{#if search_enabled}}
+				<div id="search-wrapper" class="hidden">
+					<form id="searchbar-outer" class="searchbar-outer">
+						<input type="search" name="search" id="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+					</form>
+					<div id="searchresults-outer" class="searchresults-outer hidden">
+						<div id="searchresults-header" class="searchresults-header"></div>
+						<ul id="searchresults">
+						</ul>
+					</div>
+				</div>
+				{{/if}}
+
+				<main id="main">
+					{{{ content }}}
+				</main>
+
+				<nav id="nav-wide-wrapper" aria-label="Page navigation">
+					{{#previous}}
+						<a href="{{ path_to_root }}{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+							<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+								<path d="M4 10l9 9 1.4-1.5L7 10l7.4-7.5L13 1z"/>
+							</svg>
+						</a>
+					{{/previous}}
+
+					{{#next}}
+						<a href="{{ path_to_root }}{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+							<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+								<path d="M7 1L5.6 2.5 13 10l-7.4 7.5L7 19l9-9z"/>
+							</svg>
+						</a>
+					{{/next}}
+				</nav>
+			</div>
+		</div>
+
+        {{#if livereload}}
+        <!-- Livereload script (if served using the cli tool) -->
+        <script type="text/javascript">
+            var socket = new WebSocket("{{{livereload}}}");
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload(true); // force reload from server (not from cache)
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+        {{/if}}
+
+        {{#if search_js}}
+        <script src="{{ path_to_root }}elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
+        <script src="{{ path_to_root }}mark.min.js" type="text/javascript" charset="utf-8"></script>
+        <script src="{{ path_to_root }}searcher.js" type="text/javascript" charset="utf-8"></script>
+        {{/if}}
+
+        <script src="{{ path_to_root }}book.js" type="text/javascript" charset="utf-8"></script>
+    </body>
+</html>