By Jackaltx in Digital Garden Talk — 14 Jan 2026

Which Doc Generator?

Digital Garden. I have a bookstackapp with several books that document group of ansible galaxy collections. the pages are done in markdown. I think I want to use either docusaurus or mkdocs w/ material for delivery. This documentation is meant for both human and AI. how should I evaluate these two "documentation generators"? If I want to use it with a tool like ref.tools what would make that more successful ?

Gemini

Moving from BookStack to a static site generator (SSG) like MkDocs or Docusaurus is a smart move for an Ansible-centric digital garden. Because Ansible is Python-based and largely configuration-driven, your choice depends heavily on how much "developer" overhead you want versus "content" speed.

Evaluating the Two Generators

Feature	MkDocs (Material)	Docusaurus
Best For	Fast, clean, Pythonic documentation.	Complex, interactive, versioned sites.
Tech Stack	Python (Jinja2 templates).	Node.js (React/MDX).
Learning Curve	Low. Configure everything in one YAML file.	Moderate. Requires some JS/React for deep customization.
Ansible Synergy	High. Most Ansible community projects (and Red Hat) use MkDocs.	Medium. Powerful, but perhaps overkill for simple collections.
Search	Excellent built-in client-side search.	Strong, often relies on Algolia for larger sites.

Why MkDocs + Material is likely your winner:

Since you are documenting Ansible Galaxy collections, the ecosystem is already built around Python. Tools like antsibull-docs or docsible are designed to scan your Ansible YAML and generate Markdown specifically for MkDocs. The "Material" theme is industry-standard for its "Instant Loading" and search capabilities, which feel very "Digital Garden-y."

Designing for Humans AND AI

To make your documentation "AI-Ready" (optimized for LLMs and tools like ref.tools), you should treat your docs as a structured dataset.

Predictable Heading Hierarchy: AI uses headings to "chunk" information. Never skip levels (e.g., don't go from to ).
Semantic Metadata: Use Frontmatter (YAML at the top of MD files) to define the module, collection, and version. AI tools use this to filter context.
Contextual Independence: Write each page as if it's the only page the AI will see. Instead of saying "As mentioned in the previous chapter," say "In the setup_webserver role..."
Code Block Annotations: Always use language tags (e.g., ````yaml`). For Ansible, include the full FQCN (Fully Qualified Collection Name) in examples so the AI doesn't have to guess which collection a module belongs to.

Success with `ref.tools` and LLMs

Tools like ref.tools (or RAG-based AI assistants) perform best when they can "crawl" and "chunk" your site easily.

Use llms.txt: This is a new emerging standard. Create a /llms.txt file at the root of your site that provides a concise, text-only map of your documentation specifically for LLM ingestion.
Enable "Social Cards" / Metadata: Both Docusaurus and MkDocs Material can auto-generate metadata. This helps AI understand the "summary" of a page before reading the full text.
Avoid JS-Only Content: Ensure your site is statically generated so that simple crawlers don't need to execute complex JavaScript to "see" your Ansible examples.
Use Mermaid Diagrams: Both tools support Mermaid. This is highly effective because it provides a text-based representation of logic that LLMs can actually "read" and reason about.

Next Step

Would you like me to provide a starter mkdocs.yml configuration specifically optimized for an Ansible collection "Digital Garden" layout?

The following video offers a great head-to-head comparison of these two tools to help you visualize the final output of each.

Docusaurus vs MkDocs Comparison

This video is relevant because it specifically compares the ease of setup and the feature sets of Docusaurus and MkDocs as they stand in 2025.

Claude (Opus 4.5)

Good question, and it touches on something that's becoming increasingly important—documentation that serves both humans browsing and LLMs consuming context.

Evaluation Framework

For your use case, I'd weight these factors:

Markdown fidelity — MkDocs Material wins here. It's markdown-native and your BookStack content will migrate with minimal transformation. Docusaurus uses MDX by default, which adds React component capabilities but can introduce syntax that confuses simpler parsers. If your pages are straightforward markdown, MkDocs will be a cleaner path.

AI consumption — This is where it gets interesting. For ref.tools and similar context-injection workflows, you want documentation that produces clean, semantically structured output. MkDocs Material generates simpler HTML with predictable structure. Docusaurus produces more JavaScript-heavy output with client-side rendering, which can make scraping or text extraction messier. MkDocs also has better support for generating single-file or PDF output, which is useful for creating consolidated context documents.

Navigation and cross-referencing — Both handle this well, but MkDocs Material's navigation is configuration-driven (mkdocs.yml), which fits your infrastructure-as-code mentality. You can template and generate that nav structure programmatically if needed.

Search — Docusaurus has Algolia integration baked in; MkDocs Material has excellent built-in search that works offline. For AI use, search matters less since you're typically injecting whole sections as context.

ref.tools success factors

What makes documentation work well as LLM context:

Consistent heading hierarchy (H1 → H2 → H3 without skipping)
Self-contained pages that don't rely heavily on "see other page" references
Frontmatter with clear titles and descriptions
Code blocks with explicit language tags
Avoiding deeply nested includes or transclusions that fragment meaning

MkDocs Material's mkdocs-monorepo-plugin or simple concatenation scripts can produce single consolidated markdown files per collection—essentially pre-built context chunks.

My lean

Given your Ansible automation focus, MkDocs Material is probably the better fit. It's Python-based (plays nicer with your tooling), produces cleaner output for AI consumption, and the configuration-as-code approach means you can manage it like infrastructure.

Want me to sketch out a migration approach from BookStack or a mkdocs.yml structure that would organize your collection documentation well?