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

Replace markdown_include with snippets as the former did not work well with zensical (adapts Add deprecation notice to OpenVPN pages [v6] #1029)
Switch to native zensical.toml
Decide which theme should be used (classic vs modern)
Port navigation
Update Readme.md
Table of contents > On this page in right navigation panel
Check snippts (OpenVPN deprecation notice) working
Tooltip Footnotes
Abbreviations work when defined in same page, but glossary does not; Tracking

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
Check how to implement not_in_nav, Tracker
Replace mkdocs-redirects, Tracker
Page headings are not deducted from navigation name but from document title, but they should, Tracking

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	`a0c3363`
🔍 Latest deploy log	https://app.netlify.com/projects/pihole-docs/deploys/699c5d5e0b2f770008c0802c
😎 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.

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