Switch from mkdocs-material to zensical by yubiuser · Pull Request #1311 · pi-hole/docs

yubiuser · 2025-11-17T19:25:04Z

What does this PR aim to accomplish?:

mkdocs-material is in maintenance mode and their creators build a new site generation tool called zensical (here). It offers a back-wards compatibility to mkdocs-material so the transition is quite smooth.

This is work in progress

Internal

External

Check if git-revision-date-localized-plugin is still needed, Tracker
Figure out what replaces theme/features: search.suggest and search.share
Build mode --strict is missing, affecting link validation (Fixed with https://github.com/zensical/zensical/releases/tag/v0.0.38)
Check how to implement not_in_nav, Tracker(Fixed in https://github.com/zensical/zensical/releases/tag/v0.0.70)
Replace mkdocs-redirects, Tracker (Fixed with https://github.com/zensical/zensical/releases/tag/v0.0.58)
Page headings are not deducted from navigation name but from document title, but they should, Tracking
Check how to implement validation.nav.not_found, Tracker

By submitting this pull request, I confirm the following:

I have read and understood the contributors guide, as well as this entire template. I understand which branch to base my commits and Pull Requests against.
I have commented my proposed changes within the code and I have tested my changes.
I am willing to help maintain this change if there are issues with it later.
It is compatible with the EUPL 1.2 license
I have squashed any insignificant commits. (git rebase)
I have checked that another pull request for this purpose does not exist.
I have considered, and confirmed that this submission will be valuable to others.
I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
I give this submission freely, and claim no ownership to its content.

I have read the above and my PR is ready for review. Check this box to confirm

netlify · 2025-11-17T19:25:49Z

✅ Deploy Preview for pihole-docs ready!

Name	Link
🔨 Latest commit	`161fb25`
🔍 Latest deploy log	https://app.netlify.com/projects/pihole-docs/deploys/6ae603ca644a48a9f423a657
😎 Deploy Preview	https://deploy-preview-1311--pihole-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

rdwebdesign · 2025-11-17T21:48:44Z

Figure out what replaces theme/features: search.suggest and search.share

I'm not sure if these options are available on the new system, but do we need them?

search.share only adds an icon to the search bar that copies a link to clipboard. The link will include the query string ?q=<search_string>, link this: https://docs.pi-hole.net/?q=dns.

search.suggest is useful (it works like auto-completion on the search field), but I'm not sure if this is available.

The new search window is a little different, but it also shows all results in real time while you type the search string, like mkdocs search. Not sure if the suggestions are needed.

yubiuser · 2025-11-17T22:16:41Z

The whole search was completely re-implemented. We probably don't need search.share (who is linking to search results which can change on every page change?); search.suggest is nice and might be implemented as they work on the search functionality. I don't think it is a big loss for both option, but just kept track of things that we use and which are currently not implemented.

Note: I removed markdown_extensions which were unused without listing them above.

rdwebdesign · 2025-11-20T01:12:38Z

Check how to implement not_in_nav

Not sure if we really need this.

Decide which theme should be used (classic vs modern)

Can you provide a screenshot using the "classic" theme?

yubiuser · 2025-11-20T07:19:18Z

Not sure if we really need this.

It depends if they implement warning about files not included in the navigation. Tracking here: zensical/zensical#124

Can you provide a screenshot using the "classic" theme?

This is 1:1 the current Materials for MkDocs theme we use. So all screenshots are at https://docs.pi-hole.net/
(This is why I used the 'modern' them for the Nelify preview so we can easily compare)

mwoolweaver · 2025-11-20T14:10:29Z

(This is why I used the 'modern' them for the Nelify preview so we can easily compare)

i vote modern. (though i'm sure my vote doesnt count much😂😂)

github-actions · 2025-12-06T10:46:22Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2025-12-06T10:58:45Z

Conflicts have been resolved.

github-actions · 2025-12-20T10:44:10Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2025-12-21T06:39:11Z

Conflicts have been resolved.

github-actions · 2026-01-31T10:59:22Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2026-01-31T11:37:30Z

Conflicts have been resolved.

Signed-off-by: yubiuser <github@yubiuser.dev>

…stalled as compatibility layer on musl based Alpine for the glic binary Signed-off-by: yubiuser <github@yubiuser.dev>

Signed-off-by: yubiuser <github@yubiuser.dev>

- remove some unnecessary changes; - use some color variables for better consistency; - adjust CSS selector to actually apply link color in dark mode; - adjust some colors to increase contrast and readability. Signed-off-by: RD WebDesign <github@rdwebdesign.com.br>

Signed-off-by: RD WebDesign <github@rdwebdesign.com.br>

Signed-off-by: yubiuser <github@yubiuser.dev>

Details: - Add custom color for both light and dark modes (medium-dark blue); - use the custom color as header background and change the text to white, keeping a very good contrast; - use a lighter color for link hover effect (dark mode); - add a white circle behind the Pi-hole logo on the header. Without this background the logo looks very ugly in dark mode (or on top of any dark color). - use the custom color for the active link text (light mode), increasing the contrast ratio from 3.75:1 to 9.02:1. - use the custom color as active menu item background (with white text) - contrast ratio = 10.74:1. Signed-off-by: RD WebDesign <github@rdwebdesign.com.br>

Signed-off-by: yubiuser <github@yubiuser.dev>

github-actions · 2026-10-31T15:05:52Z

Conflicts have been resolved.

yubiuser requested a review from a team as a code owner November 17, 2025 19:25

yubiuser marked this pull request as draft November 17, 2025 19:25

yubiuser force-pushed the zensical branch from 3cc46f0 to 273cbdf Compare November 18, 2025 07:45

yubiuser force-pushed the zensical branch 5 times, most recently from 204e8b4 to 30ae486 Compare November 26, 2025 19:43

github-actions Bot added the Merge Conflict label Dec 6, 2025

yubiuser force-pushed the zensical branch from 663b6dc to f9a77ec Compare December 6, 2025 10:58

github-actions Bot removed the Merge Conflict label Dec 6, 2025

yubiuser force-pushed the zensical branch from f9a77ec to 4464a50 Compare December 20, 2025 07:42

github-actions Bot added the Merge Conflict label Dec 20, 2025

yubiuser force-pushed the zensical branch from 95cd647 to c206cf1 Compare December 21, 2025 06:39

github-actions Bot removed the Merge Conflict label Dec 21, 2025

github-actions Bot added the Merge Conflict label Jan 31, 2026

yubiuser force-pushed the zensical branch from 441ac36 to 1ce9d36 Compare January 31, 2026 11:37

github-actions Bot removed the Merge Conflict label Jan 31, 2026

yubiuser and others added 29 commits October 31, 2026 16:05

zensical==0.0.50

52ccd3f

Signed-off-by: yubiuser <github@yubiuser.dev>

Update zensical==0.0.51

d9a876f

Signed-off-by: yubiuser <github@yubiuser.dev>

Remove OpenVPN from navigation

b9ccb3e

Signed-off-by: yubiuser <github@yubiuser.dev>

Update zensical==0.0.52

11a367e

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.53

50dad98

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.54

8cd7853

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.55

6b28613

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.56

2cd2144

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.57

53eb839

Signed-off-by: yubiuser <github@yubiuser.dev>

Update zensical==0.0.58 and restore redirects

3df6a3b

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.59

b3d5bca

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.62

2b1a572

Signed-off-by: yubiuser <github@yubiuser.dev>

Add zensical-studio VS code extension. It requires 'gcompat' to be in…

e8c655e

…stalled as compatibility layer on musl based Alpine for the glic binary Signed-off-by: yubiuser <github@yubiuser.dev>

Bump alpine version in devcontainer dockerfile

d8a5c1d

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.63

a2be196

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.64

5f148b3

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.65

6ecb590

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.66

f4c5e8d

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.67

11b210c

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.68

8bdebde

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.69

7ad5ea8

Signed-off-by: yubiuser <github@yubiuser.dev>

Update to zensical==0.0.70 and

2423702

Signed-off-by: yubiuser <github@yubiuser.dev>

Adjust CSS styles

8ea40d9

- remove some unnecessary changes; - use some color variables for better consistency; - adjust CSS selector to actually apply link color in dark mode; - adjust some colors to increase contrast and readability. Signed-off-by: RD WebDesign <github@rdwebdesign.com.br>

Enhance contranst for active menu link - dark mode

0437146

Signed-off-by: RD WebDesign <github@rdwebdesign.com.br>

zensical==0.0.71

f87a70d

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.72

1a1e253

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.73

0addfb2

Signed-off-by: yubiuser <github@yubiuser.dev>

zensical==0.0.74

161fb25

Signed-off-by: yubiuser <github@yubiuser.dev>

Conversation

yubiuser commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for pihole-docs ready!

Uh oh!

rdwebdesign commented Nov 17, 2025

Uh oh!

yubiuser commented Nov 17, 2025

Uh oh!

rdwebdesign commented Nov 20, 2025

Uh oh!

yubiuser commented Nov 20, 2025

Uh oh!

mwoolweaver commented Nov 20, 2025

Uh oh!

github-actions Bot commented Dec 6, 2025

Uh oh!

github-actions Bot commented Dec 6, 2025

Uh oh!

github-actions Bot commented Dec 20, 2025

Uh oh!

github-actions Bot commented Dec 21, 2025

Uh oh!

github-actions Bot commented Jan 31, 2026

Uh oh!

github-actions Bot commented Jan 31, 2026

Uh oh!

github-actions Bot commented Oct 31, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

yubiuser commented Nov 17, 2025 •

edited

Loading

netlify Bot commented Nov 17, 2025 •

edited

Loading