DITA Bookshelf User Guide

User guide for viewing, rendering, querying, and chatting with DITA documentation rendered by a React web application with a RAG Vector Search service, and AI Assistant.

Welcome to the DITA Bookshelf

The DITA Bookshelf provides an interactive web application for browsing DITA documentation, viewing rich Bootstrap components, querying content via semantic vector search (RAG Service), and chatting with an AI Assistant. Content is published from DITA source files and automatically rendered in modern web browser views.

Quick Start with Docker Compose

Launch the DITA Library application (data-store, renderer and mcp-server) using Docker Compose:

docker compose up -d

For large document sets, add the RAG vector search service by including the second compose file:

docker compose -f docker-compose.yml -f docker-compose.rag.yml up -d

Once launched, access the system services in your browser:

  • Documentation Portal: http://<renderer> — View and browse loaded documentation sets.
  • AI Assistant Chat: http://<renderer>/chat — Chat with the AI documentation assistant.
  • Data Store: http://<data-store>/api/docs — List the loaded document sets and manage them through the REST API.

Where <renderer> and <data-store> are the hosts and ports the services are running on, defaulting to localhost:3000 and localhost:4000.

Creating Documentation

Generate a document set's AST content using DITA-OT:

  1. Generating AST: Publish your DITA map using the ast-bootstrap format: 
    dita --input=path/to/document.ditamap \
     --format=ast-bootstrap
    See Generating AST for detailed instructions on AST publishing and custom header/footer templates.
  2. Generating Chrome: Generate global chrome layouts for the React web application using the ast-chrome format: 
    dita --input=path/to/document.ditamap \
     --format=ast-chrome \
     --output=path/to/output
    See Generating Chrome for overridable chrome elements.

Publishing Documentation

Upload the generated document output to the data-store via its REST API:

curl -X POST --data-binary @path/to/output/document.zip \
     -H "Content-Type: application/zip" \
     http://<data-store>/api/docs/<document-id>

The system automatically detects published document sets, builds search indices, and displays them in your documentation catalog. See Data Store Service for the full upload API, including authorization and validation rules.

Publish updates to the global chrome layout:

curl -X PUT --data-binary @path/to/output/chrome.json \
     -H "Content-Type: application/json" \
     http://<data-store>/api/chrome

Chrome updates are published immediately

Viewing, Rendering & Navigation Features

The web reader offers rich interactive controls for viewing and reading documentation:

Documentation Library Portal (/)
A visual catalog displaying all published document sets. Select any card to open its topic reader view.
Collapsible Navigation Sidebar
A multi-level Table of Contents sidebar for expanding chapters and navigating directly between topics.
Interactive Component Rendering
DITA elements (tables, accordions, alerts, badges, cards, code blocks, figures) render as live interactive Bootstrap components with column sorting, text filtering, and pagination.
RAG Vector Search & Header Search Bar
Type keywords into the header search bar or chat prompt to query topics. Requests leverage the standalone RAG Service for high-speed semantic vector ranking.
Dark Mode Switcher
Toggle between Light, Dark, and System Auto color themes via the header menu.
AI Assistant Chat (/chat)
Chat with an AI Assistant to answer questions about the documentation corpus or preview interactive topic components inline.

User Configuration (.env)

Environment variables in your .env file select the site theme, the AI Assistant's LLM provider and credentials, and service authorization:

BOOTSTRAP_THEME
Site Bootswatch theme (e.g. default, darkly, journal).
CHAT_BOT_PROVIDER
Active LLM provider: gemini, anthropic, openai, or ollama.
ANTHROPIC_API_KEY / _BASE_URL / _MODEL
Anthropic Claude credentials and model.
OPENAI_API_KEY / _BASE_URL / _MODEL
OpenAI credentials and model.
OLLAMA_BASE_URL / _MODEL / _VERSION
Local Ollama endpoint, model, and container version.
GEMINI_API_KEY / _BASE_URL / _MODEL
Google Gemini credentials and model.
MCP_SERVER_URL
Streamable HTTP endpoint of mcp-server used by /chat.
SHOW_TOOL_INVOCATIONS
Set to true to show debug badges for AI tool calls in chat.
AUTH_TOKEN
Bearer token guarding data-store's write API. Unset by default.

See Web Renderer, Search Bar & AI Chat Bot, and Data Store Service for setup details.