feat: antora-cpp-tagfiles-extension coordination

Author: alandefreitas

README.adoc

@@ -12,7 +12,7 @@ Install this extension
 
 [source,bash]
 ----
-npm i -D @alandefreitas/antora-cpp-reference-extension
+npm i -D @cppalliance/antora-cpp-reference-extension
 ----
 
 === Requirements
@@ -31,7 +31,7 @@ Append the following in your `playbook.yaml`:
 ----
 antora:
   extensions:
-    - require: '@alandefreitas/antora-cpp-reference-extension' # <1>
+    - require: '@cppalliance/antora-cpp-reference-extension' # <1>
       dependencies: # <2>
         - name: 'boost'
           repo: 'https://github.com/boostorg/boost.git'
@@ -40,9 +40,12 @@ antora:
           system-env: 'BOOST_SRC_ROOT' # <3>
 ----
 
-* <1> `npm` package name: `@alandefreitas/antora-cpp-reference-extension` (required)
-* <2> List of dependencies to be downloaded and extracted. The directory where these dependencies are extracted will be available to all components as an environment variable.
-* <3> The name of the environment variable describing where the path can be found. If this path exists and is a valid directory, it will be used as the source root for the dependency, skipping the download and extraction steps. If this is different from `variable`, the extension will set the value of `variable` to the path where the dependency is already located.
+* <1> `npm` package name: `@cppalliance/antora-cpp-reference-extension` (required)
+* <2> List of dependencies to be downloaded and extracted.
+The directory where these dependencies are extracted will be available to all components as an environment variable.
+* <3> The name of the environment variable describing where the path can be found.
+If this path exists and is a valid directory, it will be used as the source root for the dependency, skipping the download and extraction steps.
+If this is different from `variable`, the extension will set the value of `variable` to the path where the dependency is already located.
 
 Besides the `dependencies` configuration, you can also set the following options:
 
@@ -52,20 +55,24 @@ Besides the `dependencies` configuration, you can also set the following options
 | `version` | A semver range that specifies the version of MrDocs to use. | `*`
 | `allow-master` | If `true`, the extension will allow the use of the `master` branch for MrDocs if `version` is `*`. | `true`
 | `allow-develop` | If `true`, the extension will allow the use of the `develop` branch for MrDocs if `version` is `*`. | `true`
+| `module` | Antora module that will receive the generated pages (`modules/<module>/pages`). | `reference`
 |===
 
 === Components
 
-Components that will include reference documentation should set the path of the MrDocs configuration file. Append following in your `antora.yaml`:
+Components that will include reference documentation should set the path of the MrDocs configuration file.
+Append following in your `antora.yaml`:
 
 [source,yaml]
 ----
 ext:
   cpp-reference:
     config: doc/mrdocs.yml # <1>
+    module: api-ref        # <2>
 ----
 
 * <1> The path to the MrDocs configuration file relative to the worktree.
+* <2> (Optional) Override the Antora module used for the generated pages. If omitted the component inherits the module set at the playbook level (or `reference` when neither level specifies a value).
 
 For more information about MrDocs, see https://www.mrdocs.com/docs
 
@@ -80,6 +87,20 @@ You would usually include a link to the main reference page in the component's `
 * xref:reference:index.adoc[Reference]
 ----
 
+=== Coordinating with the tagfiles extension
+
+When the tagfiles extension (https://github.com/cppalliance/antora-cpp-tagfiles-extension) is also listed in your playbook, the reference tagfile is registered automatically and picked up within the same Antora run—even if you change the module name.
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@cppalliance/antora-cpp-reference-extension'
+    - require: '@cppalliance/antora-cpp-tagfiles-extension'
+----
+
+With this configuration, you don't need to copy tagfiles into your repository or commit them to source control to satisfy `cpp:` macros.
+
 == Example
 
 The `example` directory contains an example project with a component that uses the extension.