pi-hole · yubiuser · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025 · Nov 18, 2025
@@ -7,9 +7,9 @@ RUN apk add --no-cache \
     py3-pip \
     tzdata
 
-ENV USER node
+ENV USER=node
 USER ${USER}
 
-# python packages (as mkdocs) are installed in the user's home directory
+# python packages (as zensical) are installed in the user's home directory
 # but we need them to be accessible from ${PATH}
 ENV PATH="${PATH}:/home/${USER}/.local/bin"
@@ -15,8 +15,11 @@ trim_trailing_whitespace = true
 [*.yml]
 tab_width = 2
 
-[*.md]
+[*.toml]
 tab_width = 2
+
+[*.md]
+tab_width = 4
 trim_trailing_whitespace = false
 
 [*.json]

@@ -17,4 +17,4 @@ jobs:
         uses: codespell-project/actions-codespell@8f01853be192eb0f849a5c7d721450e7a467c579 #v2.2
         with:
           ignore_words_file: .codespellignore
-          skip: ./docs/routers/fritzbox-de.md,./mkdocs.yml,./package.json,./package-lock.json,./.markdownlint.json,./requirements.txt, ./MathJax-es5/*
+          skip: ./docs/routers/fritzbox-de.md,./zensical.toml,./package.json,./package-lock.json,./.markdownlint.json,./requirements.txt
@@ -14,7 +14,7 @@ This repo is the source for the official [Pi-hole documentation](https://docs.pi
 
 ### How to contribute
 
-To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar [on the mkdocs wiki](https://www.mkdocs.org/user-guide/configuration/#nav)
+To add a new link on the navigation panel you need to edit the `zensical.toml` file in the root of the repo. There is a guide for building the navbar [on the zensical documentation](https://zensical.org/docs/setup/navigation/)
 
 To add a new document or guide.
 
@@ -26,7 +26,7 @@ To add a new document or guide.
 
 ### Testing your changes
 
-When working on this repo, it is advised that you review your changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine.
+When working on this repo, it is advised that you review your changes locally before committing them. The `zensical serve` command can be used to live preview your changes (as you type) on your local machine.
 
 Please make sure you fork the repo and change the clone URL in the example below for your fork:
 
@@ -51,7 +51,7 @@ Please make sure you fork the repo and change the clone URL in the example below
     - Running the docs server:
 
     ```bash
-    mkdocs serve --dev-addr 0.0.0.0:8000
+    zensical serve --dev-addr 0.0.0.0:8000
     ```
 
 - Fedora Linux instructions (tested on Fedora Linux 28):
@@ -66,20 +66,12 @@ Please make sure you fork the repo and change the clone URL in the example below
     - Running the docs server:
 
     ```bash
-    mkdocs serve --dev-addr 0.0.0.0:8000
+    zensical serve --dev-addr 0.0.0.0:8000
     ```
 
-- Docker instructions:
-    - One-shot run:
+- Docker devcontainer instructions:
+    - We provide a `devcontainer.json` and a dockerfile which will setup the required development environment for an easy deployment. Devcontainers can be used with various editors, e.g. VS Code
 
-    ```bash
-    docker run -v `pwd`:/opt/app/ -w /opt/app/ -p 8000:8000 -it nikolaik/python-nodejs:python3.7-nodejs16 \
-      sh -c "pip install --user -r requirements.txt && \
-      /root/.local/bin/mkdocs build && \
-      npm ci && \
-      npm test && \
-      /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000"
-    ```
 
 After these commands, the current branch is accessible through your favorite browser at <http://localhost:8000>
 

@@ -418,4 +418,3 @@ Session-based authentication, while convenient and widely used, does have severa
 
 Remember, no security measure is foolproof, but by understanding the potential risks and the multiple layers of defense your Pi-hole implemented against these risks, you can make an informed decision about how to use the Pi-hole API securely in the context of your own scripts. Always use the secure transmission method (HTTPS) offered by your Pi-hole to access the API. The strong encryption will prevent attackers from eavesdropping on your requests and makes stealing your session ID basically impossible.
 
-{!abbreviations.md!}
@@ -200,4 +200,3 @@ Code | Description | Interpretation
 
 We recommend writing code that gracefully handles all possible API exceptions. The Pi-hole API is designed to support this by standardized error messages and human-readable hints for errors.
 
-{!abbreviations.md!}
@@ -1,7 +1,3 @@
----
-title: Group Management
----
-
 Groups are defined in the `group` table and can have an optional description in addition to the mandatory name of the group.
 
 Label | Type | Uniqueness enforced | Content

@@ -1,7 +1,3 @@
----
-title: Domain Database
----
-
 Pi-hole uses the well-known relational database management system SQLite3 for managing the various domains that are used to control the DNS filtering system. The database-based domain management has been added with Pi-hole v5.0. The ability to subscribe to external *allow*lists has been added with Pi-hole v6.0.
 
 ## Priorities

@@ -1,9 +1,3 @@
----
-title: Docker DHCP and Network Modes
-description: Setting up DHCP for Docker Pi-hole
-last_updated: Sat Feb 09 00:00:00 2019 UTC
----
-
 # Docker DHCP and Network Modes
 
 Docker runs in a separate network by default called a docker bridge network, which makes DHCP want to serve addresses to that network and not your LAN network where you probably want it. This document details why Docker Pi-hole DHCP is different from normal Pi-hole and how to fix the problem.

@@ -59,7 +59,7 @@ An example of how some of these variables may look in your compose file
 | :--- | :--- |
 | `TZ` | Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight. |
 | `FTLCONF_webserver_api_password` | To set a specific password for the web interface (per the quick-start example).<br><br>If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log.<br><br>You can find this password by running `docker logs pihole` and looking for "random password". See [Setting the Web Interface Password](#setting-the-web-interface-password) below for usage examples. |
-| `FTLCONF_dns_upstreams` | Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon<br><br>Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`<br><br>Supports [Docker service names and links](https://docs.docker.com/compose/networking/) instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services |
+| `FTLCONF_dns_upstreams` | Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon<br><br>Supports non-standard ports with #\[port\] number e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`<br><br>Supports [Docker service names and links](https://docs.docker.com/compose/networking/) instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services |
 
 
 ## Setting the Web Interface Password {: #setting-the-web-interface-password }

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 - Install the official OpenVPN App from the [App Store](https://play.google.com/store/apps/details?id=net.openvpn.openvpn)
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ## Create a client config file (`.ovpn`)
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ### Dual VPN Setup - Separate DNS and VPN Traffic
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 **Up until now, this wiki has been about a server set up on a cloud host, available on the public Internet. This section is aimed at a server set up in a private network like on a Raspberry Pi.**
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 If you operate your Pi-hole + OpenVPN at home, you are likely sitting behind a NAT / dynamically changing IP address. In this case, you should set up a dynamic DNS record, which allows you to reach your server. You can exchange the address that has been configured during the setup of OpenVPN like this:
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ### (optional) Secure the server with firewall rules (`iptables`)
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server. If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md).
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ## Install an operating system
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ### Optional: Only route DNS via VPN
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ### Change OpenVPN's resolvers
 

@@ -1,4 +1,6 @@
-{!guides/vpn/openvpn/deprecation_notice.md!}
+--8<--
+docs/guides/vpn/openvpn/deprecation_notice.md
+--8<--
 
 ### CRL expired
 

@@ -1,8 +1,3 @@
----
-title: Overview of Pi-hole
-description: Brief overview of Pi-hole
----
-
 <p class="text-center">
     <a href="https://pi-hole.net/">
         <img src="https://pi-hole.github.io/graphics/Vortex/Vortex_with_Wordmark.svg" width="150" height="260" alt="Pi-hole">

@@ -1,9 +1,3 @@
----
-title: Getting in touch
-description: Pi-hole contacts and social media
-last_updated: Sun Jan 13 18:33:27 2019 UTC
----
-
 While we are primarily reachable on our [Discourse User Forum](https://discourse.pi-hole.net/), we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance.
 
 - [Frequently Asked Questions](https://discourse.pi-hole.net/c/faqs)

@@ -1,17 +1,10 @@
----
-title: Pi-hole News and Blogs
-description: Sites and articles about Pi-hole
-last_updated: Sun Jan 13 19:20:35 2019 UTC
----
-
 ## YouTube/Twit/Video
 
 - [Security Now Netcast: Pi-hole](https://www.youtube.com/watch?v=p7-osq_y8i8&t=100m26s) _Oct 13, 2015_
 - [TekThing: Raspberry Pi-Hole Makes Ads Disappear!](https://www.youtube.com/watch?v=8Co59HU2gY0&t=2m) _Dec 18, 2015_
 - [Foolish Tech Show](https://www.youtube.com/watch?v=bYyena0I9yc&t=2m4s) _Dec 23, 2015_
 - [Digital Trends: 5 Fun, Easy Projects You Can Try With a $35 Raspberry Pi](https://www.youtube.com/watch?v=QwrKlyC2kdM&t=1m42s) _Mar 22, 2016_
 - [Adafruit: Raspberry Pi Quick Look at Pi Hole ad blocking server with Tony D](https://www.youtube.com/watch?v=eg4u2j1HYlI) _Jun 20, 2016_
-- [The Defrag Show: Endoscope USB Camera, The Final \[HoloLens\] Vote, Adblock Pi and more](https://channel9.msdn.com/Shows/The-Defrag-Show/Defrag-Endoscope-USB-Camera-The-Final-HoloLens-Vote-Adblock-Pi-and-more#time=20m39s) _Jan 27, 2016_
 - [Know How 355: Killing ads with a Raspberry Pi-Hole!](https://www.twit.tv/shows/know-how/episodes/355) _Nov 9, 2017_
 - [Linus Tech Tips: Block EVERY Online Ad with THIS](https://www.youtube.com/watch?v=KBXTnrD_Zs4) _Aug 28, 2019_
 

@@ -1,9 +1,3 @@
----
-title: Pi-hole Origins
-description: Software packages used in Pi-hole
-last_updated: Sun Jan 13 18:35:14 2019 UTC
----
-
 Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following technologies:
 
 - [`dnsmasq`](https://www.thekelleys.org.uk/dnsmasq/doc.html) - a lightweight DNS and DHCP server

@@ -1,9 +1,3 @@
----
-title: Prerequisites
-description: Operating system and network requirements
-last_updated: May 25 2020
----
-
 ## Hardware
 
 Pi-hole is very lightweight and does not require much processing power

@@ -1,9 +1,3 @@
----
-title: Community Projects
-description: Things built with Pi-hole
-last_updated: Sun Sep 06 14:28:14 2020 UTC
----
-
 - [The Big Blocklist Collection](https://firebog.net/)
 - [Pi-Hole in the cloud](https://blog.codybunch.com/2015/07/28/Pi-Hole-in-the-cloud/)
 - [Minibian Pi-hole](https://munkjensen.net/wiki/index.php/See_my_Pi-Hole#Minibian_Pi-hole)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -418,4 +418,3 @@ Session-based authentication, while convenient and widely used, does have severa

		Remember, no security measure is foolproof, but by understanding the potential risks and the multiple layers of defense your Pi-hole implemented against these risks, you can make an informed decision about how to use the Pi-hole API securely in the context of your own scripts. Always use the secure transmission method (HTTPS) offered by your Pi-hole to access the API. The strong encryption will prevent attackers from eavesdropping on your requests and makes stealing your session ID basically impossible.

		{!abbreviations.md!}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -200,4 +200,3 @@ Code \| Description \| Interpretation

		We recommend writing code that gracefully handles all possible API exceptions. The Pi-hole API is designed to support this by standardized error messages and human-readable hints for errors.

		{!abbreviations.md!}