nodebb-plugin-mdx-page-renderer

A NodeBB v4 plugin that serves MDX-based documentation pages with server-side rendering, automatic Doxygen C++ API reference components, and an admin panel for managing content sources. It runs on The Starport, the community hub for Freelancer (2003) modding.

How it works

• MDX files are compiled server-side using @mdx-js/mdx and rendered with React's renderToStaticMarkup - no JS is sent to the browser
• Custom components (ApiClass, ApiEnum, ApiFunction, ApiMacro, TypeLink, and badge components) pull from Doxygen JSON data at render time
• Content is pulled from archive URLs, git repositories, or written inline in the admin panel
• Code highlighting via rehype-highlight, admonition blocks (:::note), and Mermaid diagrams (client-side CDN) are supported out of the box

Content artifact format

Archive and git sources must conform to the following directory layout:

content/          <- MDX files; directory structure maps to URL paths
doxygen/          <- Optional Doxygen JSON (loaded into memory on refresh)
  classes/        <- One JSON file per C++ class
  enums/          <- One JSON file per C++ enum
  macros/         <- One JSON file per C preprocessor macro

The doxygen-to-json CLI tool generates this artifact from Doxygen XML output.

MDX component reference

All components are injected automatically - no import statement is needed in MDX files.

| Component | Props | Description | |-----------|-------|-------------| | <ApiClass name="..." /> | name | All public methods and fields for a C++ class or struct | | <ApiEnum name="..." /> | name | All values for a C++ enum | | <ApiFunction class="..." name="..." /> | class, name | A single documented method | | <ApiMacro name="..." /> | name | A C preprocessor macro with signature and expansion | | <TypeLink name="..." /> | name | Inline linked reference to a documented C++ type | | <ModuleDepNote module="..." /> | module | Standard module dependency warning block | | <VersionBadge since="..." /> | since | "Since vX.Y.Z" inline badge | | <DeprecatedBadge since="..." replacement="..." /> | since, replacement | Deprecation notice block | | <ExperimentalBadge /> | - | Experimental API warning block | | <BreakingBadge version="..." /> | version | Breaking change inline badge | | <PlatformBadge platform="..." /> | platform | Arbitrary platform context badge | | <TOC /> | - | Inline table of contents from page headings | | <ClassDiagram name="..." /> | name | Mermaid inheritance diagram (future) |

Admonitions

:::note
Content here.
:::

:::warning
Also supports: tip, danger, info
:::

Local development

Prerequisites: Node.js 20+, pnpm, a running NodeBB v4 install.

1. Clone the repo into NodeBB's node_modules/ directory, or use npm link to symlink it in
2. Activate the plugin in NodeBB's admin panel
3. Run ./nodebb build and ./nodebb restart after JS changes; the SCSS is compiled by the build step
4. Edit MDX files in the source's content directory, then use "Clear render cache" in the admin panel to pick up changes without a full restart

Admin panel features

The admin panel at /admin/plugins/mdx-page-renderer provides:

• Source types - add sources as an archive (.zip, .tar.gz, .tar.xz from a URL), a git repository (cloned and pulled on refresh), or inline (pages written directly in the panel editor)
• Inline MDX editor - write and preview MDX content without an external repository
• Refresh content - pulls the latest content from remote sources and reloads Doxygen JSON into memory
• Clear render cache - invalidates the compiled page cache so updated MDX files are re-rendered on next request, without restarting NodeBB
• Static HTML export - exports all pages as plain HTML files to the configured export path

AI usage policy

AI tooling may be used for prototyping, exploring unfamiliar APIs, and drafting boilerplate. It must not be treated as a substitute for understanding the code. Any AI-generated contribution must be:

• Manually reviewed line by line before being committed
• Manually tested against a running NodeBB instance to verify it behaves correctly
• Kept to a minimum - prefer writing code you understand over accepting AI output wholesale
• Transparently disclosed - any AI assistant used must be listed as a co-author in the commit (e.g. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>) or clearly noted in the commit description

AI-generated code that has not been tested, understood, or disclosed by a human is not acceptable in this repository.

Licence

This project is licensed under the GNU Affero General Public License v3.0.