Source Edit

Welcome to ndgBook

Overview

ndgBook is a static site generator powered by Nim's built-in documentation generator. It transforms Markdown files into a fully-featured documentation website with sidebar navigation, full-text search, and responsive design.

Unlike other site generators that require external dependencies, ndgBook leverages the Nim compiler's own RST/Markdown parser and HTML renderer. This means zero additional dependencies beyond the Nim toolchain itself.

Key features include automatic table of contents generation from your headings, syntax highlighting for code blocks in Nim, Python, Rust, and other languages, admonition blocks for tips and warnings, and a fast full-text search powered by the Nim compiler's indexing infrastructure.

Quick Example

Create a new book with a single command:

$ nimble init mybook

Then add your Markdown files to the src/ directory. Each file becomes a page in your documentation site. The directory structure is preserved in the output, so src/chapter1/intro.md becomes chapter1/intro.html.

Build your site by running:

$ nimble docs

Note: The first build compiles the Nim compiler extensions, which may take a moment. Subsequent builds are nearly instantaneous thanks to Nim's incremental compilation.

Warning: Make sure you have Nim 2.2 or later installed. Earlier versions may not support all features described in this documentation.

Philosophy

ndgBook follows the principle of "less is more." Instead of building a new parser and renderer from scratch, it extends the Nim compiler's existing documentation generator. This approach provides several advantages:

Correctness: The Nim RST/Markdown parser is battle-tested across thousands of Nim projects and the standard library documentation
Performance: The compiler's parser and renderer are compiled to native code, offering sub-second build times for most projects
Maintainability: Fewer moving parts mean fewer bugs and easier long-term support
Integration: Automatic support for Nim-specific features like {.doctype.} pragmas and Nim-flavored Markdown extensions