CxxDox¶

mkdocs-cxxdox is an MkDocs plugin that generates C++ API documentation directly from source using libclang. It parses headers, extracts Doxygen-style comments, and renders a browsable reference — namespaces, classes, functions, variables, typedefs, enums, concepts, macros — into your MkDocs site.

Status: alpha. Pre-built wheels are distributed via GitHub Releases.

Installation¶

mkdocs-cxxdox ships as a platform-specific wheel that bundles the matching libclang binary — no system LLVM/Clang install is required.

pip install https://github.com/kfrlib/cxxdox/releases/download/v0.2.1/mkdocs_cxxdox-0.2.1-py3-none-win_amd64.whl

For the best experience, pair it with the Material theme:

pip install mkdocs_cxxdox-0.2.1-py3-none-win_amd64.whl "mkdocs-material>=9.1.15"

Requirements: Python ≥ 3.9, mkdocs ≥ 1.5.

Quick start¶

Add the plugin to your mkdocs.yml:

plugins:
  - search
  - cxxdox:
      title: My Library Reference
      input:
        - include:
            - include/mylib.hpp
          compile_options:
            - -std=c++20
            - -Iinclude

Then build the site:

mkdocs serve   # or: mkdocs build

The generated reference appears under the configured path_prefix (default cxxdox/).

Demo¶

This site is itself the demo. See the Demo Library Reference for the generated documentation of the demo C++ library (demo/library.hpp, demo/library.cpp).

Symbol reference syntax¶

CxxDox extends Markdown with [[...]] references that resolve to symbols in the generated reference. The general form is:

[[<symbol>[:<flag>[:<flag>...]]]]

Where <flag> is one of: type, file, brief. Wrap a symbol in backticks (` `) when its spelling contains characters that would otherwise be parsed as Markdown — e.g. parentheses, commas, or template parameters.

Examples¶

The [[...]] syntax below is a CxxDox extension and only renders as links in the generated MkDocs site — not on GitHub. The middle column shows the raw syntax to write in your Markdown, the right column shows what it resolves to in the built docs.

Description	Syntax	Result
Simple reference	`[[Color]]`	Color
Add the symbol's type	`[[Color:type]]`	`enum` Color
Type and source file	`[[Color:type:file]]`	`enum` Color (library.hpp:121)
Type, brief, and file	`[[Color:type:file:brief]]`	`enum` Color (library.hpp:121) Enumeration of colors.
Function reference	`[[to_name(Color):type:file:brief]]`	`function` to_name(Color) (library.hpp:138) Converts a `Color` enum to its string representation.
USR-based reference	[[`c:@N@ns@Pair`:type:brief]]	`typedef` Pair Template alias for a pair of types
Reference by name	`[[Example]]`	Example
Reference by signature (backticked)	[[`fn1(std::byte, Color)`]]	fn1(std::byte, Color)
Reference by name only	`[[fn1]]`	fn1(std::byte, Color)
Template class	`[[filter<T>]]`	filter<T>
Template method	`[[filter<T>::apply]]`	filter<T>::apply(T *, size_t)
Template method with signature	[[`filter<T>::apply(T *, size_t)`]]	filter<T>::apply(T *, size_t)
Free function	[[`::global_function`]]	::global_function()
Specific overload (brief)	[[`abs(double)`:brief]]	abs(double) Computes the absolute value of a floating-point number.
Specific overload (brief)	[[`abs(int)`:brief]]	abs(int) Computes the absolute value of an integer.
Omit signature	[[`filter<T>::apply(T *, size_t)`:nosig]]	filter<T>::apply
Omit scope	[[`filter<T>::apply(T *, size_t)`:noscope]]	.apply(T *, size_t)
Omit both signature and scope	[[`filter<T>::apply(T *, size_t)`:nosig:noscope]]	.apply

Snippet¶

printf("This line appears in the test case and renders in the documentation.\n");
printf("This line doesn't appear in the test case but renders in the documentation.\n");

License¶

Apache-2.0 WITH LLVM-exception. See LICENSE.TXT. The vendored cindex.py and bundled libclang binary are part of the LLVM Project, distributed under the same license.