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

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

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

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

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

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

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

  9. Selfhosting portfolio already includes

    • Pixelfed
    • GoToSocial
    • Material for MkDocs
    • Miniflux
    • Nextcloud

    #pixelfed  #gotosocial #mkdocs #miniflux #nextcloud

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

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

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

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

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

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

    Main Documentation Page & Demo Site :

    rod2ik.github.io/tikzjax

    Please Star on #Github 🙏🙏🙏

    TikZJax.

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

    Main Documentation Page & Demo Site :

    rod2ik.github.io/tikzjax

    Please Star on #Github 🙏🙏🙏

    TikZJax.

  17. @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 🙏🙏🙏

  18. @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 🙏🙏🙏

  19. @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 🙏🙏🙏

  20. @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 🙏🙏🙏

  21. @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 🙏🙏🙏

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

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

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

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

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

  27. 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 & dark themes
    * #MkDocs with #Material #Light / #Dark themes
    100% Compatible with #Admonitions and #Content #Tabs

  28. 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 & dark themes
    * #MkDocs with #Material #Light / #Dark themes
    100% Compatible with #Admonitions and #Content #Tabs

  29. [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/

  30. [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/

  31. [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/

  32. [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/

  33. [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/

  34. 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) ```

  35. 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) ```