Reference
Architecture Overview
ndgBook extends three key Nim compiler modules:
- `compiler/docgen.nim`: The main documentation generator. Contains commandDocMarkdown, which processes Markdown files similarly to how commandDoc processes Nim source files
- `lib/packages/docutils/rstgen.nim`: The RST/HTML renderer. Contains mergeIndexes, which builds the search index, and traverseForIndex, which extracts searchable text from the document tree
- `tools/dochack/dochack.nim`: The client-side JavaScript that powers search, theme switching, and table of contents manipulation
These modules work together to provide a complete documentation pipeline: parsing, rendering, indexing, and client-side interactivity.
Index File Format
The .idx file format uses tab-separated values with six columns:
kind<tab>keyword<tab>link<tab>linkTitle<tab>linkDesc<tab>line
ndgBook adds a new entry kind, text, for full-text search paragraphs. The standard entry kinds are:
- markupTitle: Document title
- heading: Section heading
- text: Full-text paragraph (ndgBook extension)
- idx: RST :idx: role
- nim: Nim API symbol
- nimgrp: Nim overload group
When buildindex runs with --fullTextIndexation:on, it separates text entries into searchIndex.json while keeping headings and symbols in theindex.html. The client-side search then loads the JSON file for fast, offline-capable full-text search.