= Extension documentation
:page-aliases: extension-documentation.adoc

The documentation pages for the individual extensions are generated by the
`https://github.com/apache/camel-quarkus/blob/main/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java[update-extension-doc-page]` mojo
of `camel-quarkus-maven-plugin`.
The mojo is invoked from the runtime module of each extension.
The resulting AsciiDoc files are stored in
`https://github.com/apache/camel-quarkus/blob/main/docs/modules/ROOT/pages/reference/extensions[docs/modules/ROOT/pages/extensions]`.
From there, the pages are published by Antora to the Camel website.

The pages are referenced i.e. from the xref:reference/index.adoc[List of Camel Quarkus extensions]
and from Camel Quarkus items on https://{link-quarkus-code-generator}/[{link-quarkus-code-generator}].

The `update-extension-doc-page` mojo merges the https://raw.githubusercontent.com/apache/camel-quarkus/main/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc[FreeMarker template] with the following data:

* `artifactIdBase`: the `artifactId` of the runtime module without the `camel-quarkus-` prefix.
* `jvmSince`: the `<camel.quarkus.jvmSince>` property in the runtime `pom.xml`
* `nativeSince`: the `<camel.quarkus.nativeSince>` property in the runtime `pom.xml`
* `nativeSupported`: `false` if the given extension lives under `extensions-jvm`, `true` otherwise.
* `status`: the `<quarkus.metadata.status>` property in the runtime `pom.xml`. Possible values: `stable`, `preview`, `experimental`, `deprecated`. If not specified, defaults to `stable` for native-supported extensions or `preview` for JVM-only extensions.
* `unlisted`: the `<quarkus.metadata.unlisted>` property in the runtime `pom.xml`. If `true`, the extension will not be listed in the extension catalog. Defaults to `true` for JVM-only extensions.
* `deprecated`: the `<quarkus.metadata.deprecated>` property in the runtime `pom.xml`. If `true`, the extension is marked as deprecated in the documentation.
* `models`: the list of Camel
   https://github.com/apache/camel/blob/main/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/ComponentModel.java[components],
   https://github.com/apache/camel/blob/main/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/DataFormatModel.java[data formats], https://github.com/apache/camel/blob/main/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/LanguageModel.java[languages], etc. the given extension delivers.
* `intro`: the first paragraph (optional); the content of `src/main/doc/intro.adoc` in the runtime module of the given extension.
  If `intro.adoc` does not exist, the `description` from the Camel Catalog is used as the first paragraph on the page.
* `usage`: Camel Quarkus specific usage (optional); the content of `src/main/doc/usage.adoc` in the runtime module of the given extension.
* `configuration`: Camel Quarkus specific configuration options (optional); the content of `src/main/doc/configuration.adoc` in the runtime module of the given extension.
* `limitations`: Camel Quarkus specific limitations (optional); the content of `src/main/doc/limitations.adoc` in the runtime module of the given extension.

== Extension description sync

The `cq:update-quarkus-metadata` goal automatically syncs each extension's runtime `pom.xml` `<description>` with the Camel catalog.
Extensions that need a custom description (e.g. multi-model extensions or extensions where the catalog description is not suitable) can opt out by setting:

[source,xml]
----
<properties>
    <cq.descriptionSync>false</cq.descriptionSync>
</properties>
----

The property defaults to `true`.

== Overriding generated component links

Sometimes the generated component link xref within each extension doc page needs to be overridden.
Usually due to the Camel component `.adoc` file not conforming to the usual naming conventions or if a component is moved, renamed etc.

To override parts of the xref link, the following `update-extension-doc-page` configuration can be used.

[source,xml]
----
<plugin>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>update-extension-doc-page</id>
            <goals>
                <goal>update-extension-doc-page</goal>
            </goals>
            <phase>process-classes</phase>
            <configuration>
                <componentLinkOverrides>
                    <console> <!--1-->
                        <name>camel-console</name> <!--2-->
                        <kind>other</kind> <!--3-->
                        <xrefPrefix>xref:manual::</xrefPrefix> <!--4-->
                    </console>
                </componentLinkOverrides>
            </configuration>
        </execution>
    </executions>
</plugin>
----

<1> The original name of the Camel component.
<2> The overridden name of the component in the generated xref link.
<3> The overridden component kind in the generated xref link (`component`, `dataformat`, `language`, `other`).
<4> The overridden component generated xref link prefix. Useful for rare circumstances where the component requires you to link to an unconventional part of the Camel documentation (E.g. link `manual`).
+
The component link can be removed entirely by setting `xrefPrefix` to a value of `remove`. This is useful when a component is removed from the Camel core and the Camel Quarkus main branch references the `latest` Camel website docs version.