MkDocs RAG Documentation Assistant

Dokumentation ist am wertvollsten, wenn man sie befragen kann, ohne die Quelle der Wahrheit zu verlieren.

Der MkDocs RAG Documentation Assistant war eine kleine, aber vollstaendige Exploration dieser Idee: Die veroeffentlichte Dokumentation bleibt das kanonische System of Record, daraus wird ein durchsuchbarer Index gebaut, und eine Chat-Oberflaeche antwortet mit Zitaten statt nur aus Modellgedaechtnis.

Die wichtigste Designbedingung war Vertrauen. Ein Documentation Assistant sollte sich nicht wie ein generischer Chatbot mit Docs-Prompt anfuehlen. Er sollte den Retrieval-Pfad sichtbar machen, Source-Metadaten erhalten und dem Leser einen Weg zurueck zum Originalmaterial geben.

Was das Projekt macht

Das Projekt kombiniert eine MkDocs-Dokumentationsseite mit einer Retrieval-Augmented-Generation-Pipeline. Ein Nutzer stellt eine Frage innerhalb der Dokumentationsoberflaeche. Das Backend validiert die Anfrage, embedded die Query, ruft relevante Chunks aus einem abgeleiteten Vektorindex ab, baut einen geerdeten Prompt, laesst Gemini eine Antwort generieren und gibt Antwort plus Zitate zurueck.

Der Workflow hat vier Grenzen, die explizit sein sollten:

• Die Dokumentationsgrenze besitzt das Source Markdown und die MkDocs-Erfahrung fuer Leser.
• Die RAG-Service-Grenze besitzt Validierung, Embeddings, Retrieval, Prompt Construction, Generation und API-Vertraege.
• Die Derived-Index-Grenze besitzt die Vektordarstellung, aber nicht die Wahrheit. Der Index kann aus den Quelldokumenten neu gebaut werden.
• Die operative Grenze haelt den Assistant durch kontrolliertes Reindexing mit Dokumentationsaenderungen synchron.

MkDocs RAG Documentation Assistant Architektur-Workflow.

Diese Struktur zaehlt, weil der Assistant nur dann nuetzlich ist, wenn jede Ebene eine klare Verantwortung hat:

• Die Dokumentation bleibt das System of Record.
• Der Vector Store ist abgeleitete Infrastruktur und kann neu gebaut werden.
• Der Retriever begrenzt das Context Window auf relevante Abschnitte.
• Die Generation wird auf den abgerufenen Kontext beschraenkt.
• Zitate sind Teil des Trust Models, nicht nur Darstellung.
• Reindexing ist ein operativer Workflow, kein gelegentliches Aufraeumen.

Warum MkDocs als Frontend sinnvoll war

MkDocs war passend, weil der Assistant nah am Quellmaterial blieb. Der Inhalt existierte bereits als strukturiertes Markdown, die Navigation war fuer Leser vertraut, und der Assistant konnte hinzugefuegt werden, ohne die Dokumentationsseite in ein separates Produkt zu verwandeln.

Das Frontend nutzte:

• MkDocs mit dem Material-for-MkDocs-Theme.
• Eine schlanke JavaScript-Chat-Oberflaeche.
• Responsive Verhalten fuer Desktop und Mobile.
• Light- und Dark-Mode-Unterstuetzung.
• Klickbare Zitate zurueck in relevante Dokumentationsabschnitte.

Die Designentscheidung war, den Assistant nicht wie eine separate Anwendung wirken zu lassen. Er sollte neben der Dokumentation sitzen, dieselbe Informationsarchitektur respektieren und Leser schnell von Frage zu zitierter Quelle fuehren.

Backend-Architektur

Das Backend war bewusst von der Dokumentationsoberflaeche getrennt. Dadurch blieben Secrets, Modellaufrufe, Indexing-Logik und API-Vertraege aus dem Browser heraus, und der Assistant wurde als Service deploybar statt als Skript in einer statischen Seite.

Ich nutzte FastAPI, weil es eine klare API-Oberflaeche, schnelle Iteration und gute Unterstuetzung fuer typisierte Request- und Response-Modelle bietet.

Die Backend-Verantwortlichkeiten waren:

• Chat-Anfragen aus der Dokumentationsoberflaeche annehmen.
• Eingehende Fragen embedden.
• Den Vector Store nach relevanten Chunks durchsuchen.
• Gefundenen Kontext mit Source-Metadaten formatieren.
• Das Generierungsmodell aufrufen.
• Antwort und Zitate zurueckgeben.
• Health- und Reindexing-Endpunkte bereitstellen.

Die wichtigsten API-Endpunkte waren:

• POST /api/chat: eine Frage zur Dokumentation stellen.
• GET /api/models: verfuegbare Modelloptionen anzeigen.
• POST /api/reindex: den Vektorindex nach Dokumentationsaenderungen neu bauen.
• GET /health: Health Check.
• GET /docs: automatisch erzeugte FastAPI-Dokumentation.

Diese Grenze macht das System leichter deploybar, sicherer, beobachtbarer und aenderbar.

Ingestion der Dokumente

Die Ingestion-Pipeline ist der Punkt, an dem viele RAG-Systeme zuverlaessig werden oder leise scheitern. Das Modell kann nur zitieren, was die Pipeline erhaelt. Chunking und Metadaten sind deshalb Teil des Produktvertrags, nicht nur Implementierungsdetail.

Der Prozess startet mit den Markdown-Dateien der Dokumentationsseite:

1. Das konfigurierte Docs-Verzeichnis nach Markdown-Dateien scannen.
2. Dokumente entlang von Headings aufteilen.
3. Overlap hinzufuegen, damit Chunks genug Kontext behalten.
4. Embeddings fuer jeden Chunk erzeugen.
5. Vektoren mit Source-Metadaten speichern.

Ohne diese Metadaten kann der Assistant vielleicht antworten, aber nicht erklaeren, woher die Antwort kommt. Fuer Documentation Assistants sind Zitate keine Dekoration. Sie sind Teil des Trust Models.

Retrieval und Generation

Wenn ein Nutzer eine Frage stellt, embedded das System die Query mit demselben Embedding-Modell, das beim Indexing verwendet wurde. Danach wird semantisch gegen den Vector Store gesucht, und die Top-k-Chunks werden abgerufen.

Der Kontext wird in einen Prompt formatiert und an Gemini uebergeben. Der Output ist nur dann wertvoll, wenn er auf die Source Chunks zurueckverfolgbar ist. Deshalb enthaelt der Response-Vertrag sowohl Antworttext als auch Zitate.

Das Muster ist einfach, zeigt aber die echten RAG-Trade-offs:

• Kleine Chunks verbessern Praezision, koennen aber Kontext verlieren.
• Grosse Chunks erhalten Kontext, koennen aber Relevanz verwaessern.
• Mehr Chunks erhoehen Coverage, aber auch Prompt-Groesse.
• Gute Zitate erhoehen Vertrauen, brauchen aber saubere Metadaten.

Vector Storage

Fuer lokale Entwicklung war ChromaDB ausreichend. Es gab mir einen praktischen Vector Store fuer Embeddings und Similarity Search, ohne das Projekt zu frueh in schwere Infrastruktur zu ziehen.

Fuer eine echte Produktionsversion waere ich vorsichtiger bei Persistenz, Access Patterns und operativem Verhalten. Eine verwaltete Datenbank mit Vector Support, etwa PostgreSQL mit pgvector, waere natuerlicher, sobald der Assistant Teil eines groesseren Produkts wird.

Der wichtige Punkt ist: Der Vector Store ist derived data. Er kann aus dem Markdown-Source neu gebaut werden. Das sollte das Design praegen:

• Quelldokumente versionieren.
• Ingestion wiederholbar machen.
• Reindexing sicher machen.
• Den Vector Store als disposable infrastructure behandeln, nicht als Quelle der Wahrheit.

Reindexing

Dokumentation aendert sich, also muss sich der Index mit aendern.

Das Projekt enthaelt einen Reindexing-Endpunkt, der den bestehenden Vector Store leert, Markdown erneut scannt, Embeddings neu erzeugt und den suchbaren Index aktualisiert.

In Produktion wuerde ich diesen Pfad mit dem Dokumentations-Deployment verbinden, damit das Wissen des Assistants mit den veroeffentlichten Docs synchron bleibt.

Deployment Shape

Die Deployment-Form zaehlt, weil ein Documentation Assistant Teil der Dokumentationserfahrung wird. Er braucht eine klare Backend-/Frontend-Grenze, kontrollierbares Reindexing, Secret Management und genug Observability, um Retrieval-, Prompt-, Modell- und Content-Probleme auseinanderhalten zu koennen.

Die natuerliche Google-Cloud-Form waere:

• Cloud Run fuer den FastAPI-Backend-Service.
• Firebase Hosting oder ein anderer Static Host fuer MkDocs.
• Secret Manager fuer API Keys.
• Cloud Build und Artifact Registry fuer Container Builds.
• Cloud Logging fuer grundlegende Observability.

Was ich gelernt habe

Dieses Projekt hat RAG weniger wie ein Prompt Pattern und mehr wie ein Datenprodukt wirken lassen. Die Kernarbeit ist nicht “ein Modell ueber Docs fragen”. Sie ist, einen vertrauenswuerdigen Pfad von Source Material zu abgeleitetem Index zu generierter Antwort zu pflegen.

Die wichtigsten Lektionen:

• Retrieval-Qualitaet bestimmt Antwortqualitaet haeufiger als der Prompt.
• Gutes Chunking ist Produktdesign, nicht nur Textverarbeitung.
• Zitate brauchen Metadaten-Disziplin von Anfang an.
• Reindexing ist Teil des Systems.
• Der Vector Index sollte aus Source-Dokumenten reproduzierbar sein.
• Ein Documentation Assistant braucht klares Fehlerverhalten, wenn die Docs keine Antwort enthalten.

Was ich als Naechstes verbessern wuerde

Die naechste Version sollte Evaluation und Observability staerker machen:

• Ein kleines Testset von Dokumentationsfragen mit erwarteten Source Sections.
• Retrieval-Metriken, die messen, ob die richtigen Chunks zurueckkommen.
• LLM-as-a-judge Checks fuer Groundedness und Answer Relevance.
• Trace Logging pro Request, damit Retrieval, Prompt Construction und Generation separat debuggt werden koennen.
• User Feedback zur Nuetzlichkeit von Antworten.
• Einen sicheren Fallback, wenn der Kontext nicht ausreicht.

Projektlinks

• GitHub Repository: github.com/ThamuMnyulwa/mkdocs_rag
• Portfolio-Seite: MkDocs RAG Documentation Assistant

Schlussgedanke

RAG ist eine Systemgrenze, kein Feature. Source Content, Chunking, Embeddings, Retrieval, Prompt Construction, Answer Generation, Citation, Evaluation und Deployment beeinflussen alle, ob man dem Assistant trauen kann.

Wenn diese Teile sichtbar und austauschbar sind, wird die Architektur leichter zu betreiben und zu verbessern.