#mkdocs — Public Fediverse posts

At #IOER_FDz we faced a common challenge: as our technical workflows, data publication guidelines, and infrastructure grows, we realized colleagues rarely read through our extensive documentation. Attention is limited, and when someone needs to solve a specific problem, large guides are rarely read. We needed a communication agent that could bridge the gap between individual questions and our shared internal knowledge base.

To address this, we now have an embedded #AnythingLLM assistant into our Material for MkDocs documentation. It works great! Here are a few interesting technical infos:

- To keep internal data locally and avoid commercial APIs, the inference is handled on university HPC hardware via ScaDS.AI API (TU Dresden). We paired `meta-llama/Llama-3.3-70B-Instruct` with `Qwen/Qwen3-Embedding-4B` to bypass the context window bottlenecks of smaller default embedders.

Feeding raw documentation into a RAG vector database was not _so_ trivial:

1. Ingesting raw repository Markdown caused the LLM to hallucinate URLs. It outputted broken relative `.md` paths, lacked awareness of the actual navigation hierarchy, and character-based chunking cut long tables off from metadata headers.
2. We rely on a number of mkdocs plugins (macros, live database tables pulled in CI&CD, `gen-files`). This meant that the raw repository files do not contain the final compiled text, so the LLM was first missing part of the information.

I added a native MkDocs build hook (`mkdocs_llm_hook.py`). The hook intercepts the compiled Markdown after macros are executed, resolves internal relative links to absolute production URLs, semantically pre-chunks content along Markdown headings (`#`, `##`, `###`), and produces hash-anchored links for the LLM. Metadata (`Canonical_URL` and `Document_Hierarchy`) is added to each chunk before syncing with the AnythingLLM API during `mkdocs build`.

I documented the hook script, system prompt, model parameters, and UI fixes in a Gist for those interested here:

https://gist.github.com/Sieboldianus/8c14da1370891ba2fcdf09882bd78daf

It is a nice way to help colleagues find needed information faster and with better relevance filtering. Accessibility bonus: You can ask it in any language!

#MkDocs #AnythingLLM #RAG #ScaDS #Python #DevOps #OpenSource

@autkin

Not really — they are independent projects, not a fork.

The visual similarity is likely because both use Material for #MkDocs, a static-site-generator/documentation theme, rather than sharing a codebase.

docker-mailserver is a separate, configuration-file-based containerized mail stack; #mailcow is a broader multi-container suite with its own admin UI and integrated groupware components.

#Mailserver #SelfHosting #Docker

@stephenway oui, une quinzaine de projets #django #flask
Essentiellement du lint #Ruff #ty #yamllint et du #sphinx, un peu de #mkdocs

I still don't really know what to do with the mkdocs drama¹. There is a fork called properdocs while the mkdocs-material devs seem to recommend their own brand-new static-site generator Zensical². Now, someone forked mkdocs-material, but statements like these³ make me worry that they'll vibe-code it into the ground. Since I don't use any mkdocs plugins, maybe Zensical is fine?

¹ https://fpgmaas.com/blog/collapse-of-mkdocs/

² https://squidfunk.github.io/mkdocs-material/blog/

³ https://jaywhj.github.io/mkdocs-materialx/differences

#mkdocs #StaticSiteGenerator #Markdown

@rod2ik/ #TikZjaX is now in version 1.5.0

It has loads of new #TikZ -based #LaTeX #packages, natively , to draw on Standalone web #HTML pages and/or #mkdocs pages, with Light and Dark modes.

* #tkz-tab for #maths #variation / #sign tables
* #Physics
* #Circuitikz
* #Chemfig
* #Kinematikz
* #Yquant
* #Tikz-feynhand
* #Braids
* #Pgf-spectra
* etc..

Main Documentation Page & Demo Site :

https://rod2ik.github.io/tikzjax

Please Star on #Github 🙏🙏🙏

Dreaming to draw #TikZ figures and #tkz-tab #Maths #variation / #sign #tables on #web #pages and #MkDocs ???

Hava a look to @rod2ik / #tikzjax :
Now in v1.1.14 (stable)

* Project Documentation & Demo Site :
rod2ik.github.io/tikzjax/

Enjoy! and Star the #Opensource #Project on #GitHub 🙏🙏🙏

TikZJax.

Dreaming to draw #TikZ figures and #tkz-tab #Maths #variation / #sign #tables on #web #pages and #MkDocs ???

Have a look to @rod2ik / #tikzjax :
Now in v1.1.14 (stable)

* Project Documentation & Demo Site :
https://rod2ik.github.io/tikzjax/
* Npm :
https://www.npmjs.com/package/@rod2ik/tikzjax
* jsDeliver CDN :
https://www.jsdelivr.com/package/npm/@rod2ik/tikzjax

Enjoy! and Star the #Opensource #Project on #GitHub 🙏🙏🙏

Was surprised to see a rather "unusual" warning when running mkdocs build for a project.

Can anybody (who knows the circumstances more deeply) summarize the #mkdocs vs #zensical drama? (the root causes, as seen by a dispassionate third party 😅 ).

On the face of it is seems akin to the #wordpress #wpengine story, a conflict about money and control after an open source project becomes more widely adopted.

Maybe I should have stayed with sphinx 😟

[NEW] @rod2ik / #TikZJax v1.0.0 (stable) is now available on npm registry !!! 😎😎😎

https://www.npmjs.com/package/@rod2ik/tikzjax/

Reminder: ¡ AT LAST !

@rod2ik/ #tikzjax easily & natively renders #maths #variation #tables / #sign #tables on web pages with Dark Themes, #LaTeX style with #tkz-tab :

* custom web pages with dark themes
* #MkDocs with #Material #Light / #Dark themes
100% Compatible with #Admonitions and #Content #Tabs

Project Documentation site is here :

https://rod2ik.github.io/tikzjax/

¡ AT LAST !
#Drawing #math #variations #tables / #sign #tables on a #web #page, #LaTeX Style with #tkz-tab syntax, is now super easy !

Natively compatible :

* On #HTML pages with script tags
* On #MkDocs, #Material #Dark themes with #tikzjax code blocs

https://rod2ik.github.io/tikzjax/

¡ AT LAST !
#Drawing #math #variations #tables / #sign #tables on a #web #page, #LaTeX Style with #tkz-tab syntax, is now super easy !

Natively compatible :

* On #HTML pages with script tags
* On #MkDocs, #Material #Dark themes with #tikzjax code blocs

rod2ik.github.io/tikzjax/

RE: https://bsky.app/profile/did:plc:epi5fsta2mfja2jqbua4dl2f/post/3mp34kewcqk2h

TikZJax.

100% compatible with #Material for #MkDocs #Admonitions (Collapsible, or not )
AND with #Content #Tabs.

Two syntaxes :

1. With (very easy) <script> #tags
2. With #tikzjax #Markkdow #code #blocs
```tikzjax
(Your Math Table)
```

I have the pleasure to announce v1 of my #rod2ik / #TikZJax #fork :

* #TîkZ Figures in #HTML AND #MkDocs
* tkz-tab #Math #Variation #Tables / #Math #Sign #Tables in #HTML AND #MkDocs

Natively compatible with #Material #Light / #Dark #Themes

TikZJax.

I have the pleasure to announce v1 of my #rod2ik / #TikZJax #fork :

* #TîkZ Figures in #HTML AND #MkDocs
* tkz-tab #Math #Variation #Tables / #Math #Sign #Tables in #HTML AND #MkDocs

Natively compatible with #Material #Light / #Dark #Themes

At last! Drawing #Maths #Variation #Tables & #Maths #Sign #Tables, #LaTeX style , on the web , is now made so easy ! 😎

https://rod2ik.github.io/tikzjax/

#mathematics #science #physics
#maths #mathématiques #matemáticas
100% #free #opensource #foss , what else ?

📝 Ende von MkDocs

Python-Projekte werden häufig mit Material for MkDocs dokumentiert. Das habe ich auch lange genutzt, nach einem Streit zwischen den Entwickler:innen splittern diese sich auf in Zensical, ProperDocs, MkDocs 2. Nun muss ich mir überlegen, was ich für meine Projekte in Zukunft nutzen möchte und habe mich noch nicht abschließend entscheiden können.

Ganzer Beitrag: https://martin-ueding.de/posts/ende-von-mkdocs/

#MkDocs #Softwareentwicklung #Markdown #VitePress #Zensical

We start to convert our #b1gMail Wiki on #GitHub to Markdown and using Zensical for HTML documentation: https://docs.b1gmail.org

#zensical #mkdocs #documentation #email #hosting #selfhosting #mailserver #opensource

Seems like MkDocs 2.0 is aiming for being unusable: https://github.com/encode/mkdocs?tab=contributing-ov-file#maintainer-driven-issues

Can also very much recommend this blog post: https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

#opensource #mkdocs

¡Diablos! Mi página web está construida con el tema Material que funciona sobre MkDocs. Lo amo, es muy potente. Y mientras la renderizaba me encontré con una advertencia en la terminal y un enlace a la siguiente página ⚠️:

https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

#mkdocsMaterial #mkdocs #zensical #materialformkdocs

CVE Alert: CVE-2026-7159 - douinc - mkdocs-mcp-plugin - https://www.redpacketsecurity.com/cve-alert-cve-2026-7159-douinc-mkdocs-mcp-plugin/

#OSINT #ThreatIntel #CyberSecurity #cve-2026-7159 #douinc #mkdocs-mcp-plugin

Statische Seiten: Ist Zensical der legitime Nachfolger von MkDocs (Material)

Als ich im Juni letzten Jahres MkDocs (genauer: Material für MkDocs) wiederentdeckte, war ich fasziniert. Denn mit diesem freien (BSD-Lizenz), in Python geschriebenen, Markdown-basierten Generator für statische Seiten, hatte ich bereits sehr gute Erfahrungen gemacht. https://kantel.github.io/posts/2026042101_zensical/ #MkDocs #Zensical #Markdown #StatischeSeiten #Zettelkasten #Webworking

Ytterligare en bra grej med MkDocs som jag använder för sajten är att när jag kommer på nåt som vore bra så finns det redan en plugin för det.

Nu kan jag definiera priser och liknande i en fil och det uppdateras överallt där det används

#mkdocs

Info für Leitfaden-Maintainer zur Umstellung der #lernOS Produktionskette von #Mkdocs auf #Zensical: https://community.cogneon.de/t/migration-von-mkdocs-zu-zensical-lernos-produktionskette/4298

I am now using #Zensical for my #documentation website, using the same code I used for Materials for #mkdocs. I converted the mkdocs.yml to zensical.toml using #chatgpt, and I didn't like the TOML format. It looks unnecessarily complicated. So I will continue using YAML until it becomes necessary.