feat: support Lua and JavaScript extensions

CMakeLists.txt

@@ -176,6 +176,31 @@ else()
     )
 endif()
 
+# Generate the mrdocs.set allowlist artefacts from
+# src/lib/Extensions/AllowedFields.json: a constexpr `kSettableFields[]`
+# array consumed by SetMember.cpp at runtime, and an AsciiDoc table
+# included by docs/modules/ROOT/pages/extensions.adoc. Same JSON drives
+# both, so the runtime allowlist and the rendered reference cannot
+# drift.
+set(ALLOWED_FIELDS_JSON
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/lib/Extensions/AllowedFields.json")
+set(ALLOWED_FIELDS_SCRIPT
+    "${CMAKE_CURRENT_SOURCE_DIR}/util/generate_extension_allowed_fields.py")
+set(ALLOWED_FIELDS_CPP
+    "${CMAKE_CURRENT_BINARY_DIR}/include/mrdocs/Extensions/AllowedFields.gen.hpp")
+set(ALLOWED_FIELDS_ADOC
+    "${CMAKE_CURRENT_SOURCE_DIR}/docs/modules/ROOT/partials/extensions-allowed-fields.adoc")
+add_custom_command(
+    OUTPUT ${ALLOWED_FIELDS_CPP} ${ALLOWED_FIELDS_ADOC}
+    COMMAND ${PYTHON_EXECUTABLE} ${ALLOWED_FIELDS_SCRIPT}
+        ${ALLOWED_FIELDS_JSON}
+        ${ALLOWED_FIELDS_CPP}
+        ${ALLOWED_FIELDS_ADOC}
+    DEPENDS ${ALLOWED_FIELDS_JSON} ${ALLOWED_FIELDS_SCRIPT}
+    COMMENT "Generating mrdocs.set allowlist artefacts"
+    VERBATIM
+)
+
 #-------------------------------------------------
 #
 # Docs build
@@ -313,6 +338,7 @@ list(APPEND LIB_SOURCES
     ${CMAKE_CURRENT_BINARY_DIR}/include/mrdocs/Version.hpp
     ${CMAKE_CURRENT_BINARY_DIR}/include/mrdocs/PublicSettings.hpp
     ${CMAKE_CURRENT_BINARY_DIR}/src/lib/Lib/PublicSettings.cpp
+    ${ALLOWED_FIELDS_CPP}
 )
 add_library(mrdocs-core ${LIB_SOURCES})
 target_compile_features(mrdocs-core PUBLIC cxx_std_23)

docs/modules/ROOT/nav.adoc

@@ -4,7 +4,9 @@
 * xref:usage.adoc[Getting Started]
 * xref:config-file.adoc[]
 * xref:commands.adoc[Documenting the Code]
+* xref:addons.adoc[]
 * xref:generators.adoc[]
+* xref:extensions.adoc[]
 * xref:design-notes.adoc[]
 * xref:reference:index.adoc[Library Reference]
 * Contribute

docs/modules/ROOT/pages/addons.adoc

@@ -0,0 +1,58 @@
+= Addons
+
+Mr.Docs is customised through *addons*: directory trees that hold custom Handlebars templates, helper scripts and extension scripts.
+This page describes addons as a whole; what goes in each subdirectory is covered on xref:generators.adoc[Generators] and xref:extensions.adoc[Extensions].
+
+== Default and replacement addons
+
+Mr.Docs ships a built-in addon at `share/mrdocs/addons/`.
+It contains the default Handlebars templates, helpers and any baseline scripts.
+
+The `addons` configuration option replaces it:
+
+[source,yaml]
+----
+addons: /path/to/custom/addons
+----
+
+The replacement is wholesale: your addon should provide everything Mr.Docs needs for the generators you intend to use.
+
+== Supplemental addons
+
+The more common pattern is to *layer* a small addon on top of the built-in one rather than replace it entirely.
+That is what `addons-supplemental` is for:
+
+[source,yaml]
+----
+addons-supplemental:
+  - addons
+  - /path/to/another
+----
+
+Each supplemental addon is layered on top of the base addon in the order listed.
+
+== Layout
+
+[source,text]
+----
+<addons>/
+|-- generator/
+|   |-- common/{partials,helpers}/        # shared across output formats
+|   `-- <fmt>/{layouts,partials,helpers}/ # per-format (html, adoc, ...)
+`-- extensions/
+    |-- *.js
+    `-- *.lua
+----
+
+* `generator/` -- Handlebars templates and helpers for the output stage. Detailed in xref:generators.adoc[Generators].
+* `extensions/` -- scripts that run after corpus construction and can mutate symbols before any generator sees them. Detailed in xref:extensions.adoc[Extensions].
+
+== Discovery
+
+Mr.Docs visits addons in this order:
+
+. The base addon (the built-in `share/mrdocs/addons/` or whatever `addons` points at).
+. Each entry of `addons-supplemental`, in the order listed.
+
+For templates and helpers, the rule is *last wins*: a file in a supplemental addon overrides a same-named file in earlier addons.
+For extensions, every script across every addon is collected and run in alphabetical order by full path; there is no override semantic.