home.social

#mkdocs — Public Fediverse posts

Live and recent posts from across the Fediverse tagged #mkdocs, aggregated by home.social.

fetched live
  1. 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:

    gist.github.com/Sieboldianus/8

    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

  2. @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

  3. 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?

    ¹ fpgmaas.com/blog/collapse-of-m

    ² squidfunk.github.io/mkdocs-mat

    ³ jaywhj.github.io/mkdocs-materi

    #mkdocs #StaticSiteGenerator #Markdown

  4. @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 :

    rod2ik.github.io/tikzjax

    Please Star on #Github 🙏🙏🙏

  5. 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 😟

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

    npmjs.com/package/@rod2ik/tikz

    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 :

    rod2ik.github.io/tikzjax/

  7. 📝 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: martin-ueding.de/posts/ende-vo

    #MkDocs #Softwareentwicklung #Markdown #VitePress #Zensical

  8. ¡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 ⚠️:

    squidfunk.github.io/mkdocs-mat

    #mkdocsMaterial #mkdocs #zensical #materialformkdocs

  9. 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. kantel.github.io/posts/2026042 #MkDocs #Zensical #Markdown #StatischeSeiten #Zettelkasten #Webworking

  10. 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

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