use sub-chapters for blocks documentation

README.md

@@ -2,8 +2,9 @@
 
 *Building blocks for self-hosting with battery included.*
 
-SHB's (Self Host Blocks) goal is to provide a lower entry-bar for self-hosting. SHB provides opinionated [building blocks](#building-blocks) fitting together to self-host any service
+SHB's (Self Host Blocks) goal is to provide a lower entry-bar for self-hosting. SHB provides
-you'd want. Some [common services](#provided-services) are provided out of the box.
+opinionated [building blocks](#building-blocks) fitting together to self-host any service you'd
+want. Some [common services](#provided-services) are provided out of the box.
 
 Each building block defines a part of what a self-hosted app should provide. For example, HTTPS
 access through a subdomain or Single Sign-On. The goal of SHB is to make sure those blocks all fit

docs/blocks.md

@@ -0,0 +1,35 @@
+# Blocks {#blocks}
+
+Blocks help you self-host apps or services. They define and implement a specific function like
+backup or secure access through a subdomain. Each block is designed to be usable on its own and to
+fit nicely with others.
+
+In practice, a block defines a contract that must be followed to implement a specific self-hosting
+function. It also comes with a unit test and NixOS VM test suite to ensure any implementation
+follows the contract.
+
+As an example, let's take the HTTPS access block which allows for a service to be accessible through
+a specific subdomain. In Nix terms, this block defines at minimum the inputs:
+
+- subdomain,
+- domain,
+- and upstream address of the service.
+
+It defines no outputs but has one major side effect:
+
+- the service should be accessible through HTTPS at `https://subdomain.domain`.
+
+Anything that provides the inputs and expected outputs and side effects defined by the block can be
+used to fulfill its contract. In this example, we could use any of Nginx, Caddy, Haproxy or others.
+
+Self Host Blocks provides at least one implementation for each block and allows you to use your own
+implementation if you want to, as long as it passes the tests. You can then use blocks to improve
+services you already have deployed.
+
+```{=include=} chapters html:into-file=//blocks-backup.html
+modules/blocks/backup/docs/default.md
+```
+
+```{=include=} chapters html:into-file=//blocks-monitoring.html
+modules/blocks/monitoring/docs/default.md
+```

docs/manual.md

@@ -7,12 +7,8 @@
 preface.md
 ```
 
-```{=include=} chapters html:into-file=//blocks-backup.html
+```{=include=} chapters html:into-file=//blocks.html
-modules/blocks/backup/docs/default.md
+blocks.md
-```
-
-```{=include=} chapters html:into-file=//blocks-monitoring.html
-modules/blocks/monitoring/docs/default.md
 ```
 
 ```{=include=} chapters html:into-file=//demo-homeassistant.html