Improving the documentation

The Apache Camel project loves your help with improving the documentation, whether its a tiny typo fix, or adding more details to an existing component, etc.

This page only describes working with the 'documentation' portion of the website. Other portions are written in markdown and built using Hugo.

Simple changes

If there’s an edit this page button at the top right of the page and you wish to propose a simple change such as fixing a typo or rewording something, use this very simple process. For more complicated changes, including changing xrefs, adding, removing or renaming pages, and significant organizational changes, please use the process described on this page.

Where to find the documentation

All of the documentation accessible in the left-hand navigation panel in the documentation portion of the website is managed in the AsciiDoc format and built with the Antora static site generator. As of November 2021, by far the most capable Asciidoc editor is the Intellij Asciidoc plugin, which works with all Intellij editor products including the free IDEA Community Edition. The plugin preview is more capable than viewing a local Asciidoc file with a browser plugin as it has some understanding of Antora structure. Note that the only reliable way to preview your changes is with a full build of the Antora portion of the website.

The files have the extension .adoc and are managed in the Camel repositories. General documentation is usually directly editable. Component specific documentation is partially or entirely generated from other metadata sources which are in turn generated from the code, often from javadoc. Altering generated documentation requires finding the original source, which varies by project. Editable pages are found in several different places in the repositories:

Main camel repository
Camel components

In the src/main/docs folder for the component or camel module. These are symlinked to under docs/components.

EIPs

In the core/camel-core-engine/src/main/docs folder.

Core languages

In the core/camel-core-languages/src/main/docs folder. Note that many languages are under components.

User manual and FAQS

In the /docs/user-manual folder.

Camel Karaf

In the docs folder.

Camel Spring Boot

Most documentation is generated and appended to the component documentation it applies to. Editable pages are under docs/spring-boot and core/camel-spring-boot/src/main/docs and core/camel-spring-boot-xml/src/main/docs.

Other subprojects
camel-k, camel-k-runtime

Under docs. There is no generated camel-k documentation.

camel-kafka-connector

Editable pages are under docs. Most documentation is generated directly from the generated json files for each connector under connectors/<connector-name>/src/generated/resources.

camel-kamelets

Only docs/modules/ROOT/pages/index.adoc is editable. All other documentation is generated from the kamelet yaml descriptors.

camel-quarkus

Editable pages are under docs. Pages under docs/modules/ROOT/pages/reference/components and docs/modules/ROOT/pages/reference/extensions are generated, including optional snippets from e.g. extensions/activemq/src/main/doc.

camel-quarkus-examples

Editable pages are under docs.

Creating a documentation pull request.

Simple changes such as typo fixes or rewording can usually be done directly at GitHub after pressing the edit this page button at the top left of each page. Note that if the page source starts with a comment that the page is copied or generated this will not work! Please do not use this method if you are changing any xrefs or making significant changes to format; instead follow the procedure below.

  1. Fork/clone the appropriate repository from GitHub and switch to the branch you are working with.

  2. Create a branch for your work with a name starting with the original branch name, e.g. git switch -c main-doc-fix

  3. Edit the .adoc sources as needed. Preview your work in the Intellij Asciidoc plugin preview or in a browser with an Asciidoctor extension installed.

  4. Do a local website build with your changes.

  5. Commit and push your work and create a PR in the (sub)project repository.

  6. Fork/clone the camel-website repository, and create an appropriate branch, e.g. git switch -c camel-quarkus-main-456.

  7. Locate the project you are working with in the antora-playbook.yml under sources, and locate the branch you have altered under the appropriate -url.

    1. Comment out the original source URL and replace it with the URL of your fork.

    2. Leaving the original branch as a comment, alter the branch to e.g. - main-doc-fix using your branch name.

    3. Make sure that all other branches used for the documentation are up to date in your fork. To do this, for each such branch, execute

git switch <branch>
git pull
git push <fork>

  1. Commit the change to the playbook, push it to your camel-website fork, and open a PR against camel-website. CI will build your change and, if successful, will deploy a preview on Netlify. There will be an email with the preview URL.

  2. Check for build problems and examine the preview.

  3. Upon approval, your content PR will be merged. Unless you have made a considerably more extensive change than described above, the camel-website PR will not need to be merged and may be closed.

How to build the website locally, with your changes

First, make sure you have yarn, version >= 3.1.0, installed globally.

Directory layout and initial setup

You need a single directory, such as camel, that contains all the camel subprojects you are working with, and the camel-website project.

cd camel
git clone https://github.com/apache/camel-website.git

Unless you are on a linux system you will need to adjust the yarn cache/unplugged to work with your OS:

cd camel-website
yarn update:cache

Run a build against the remote source repos to check that it works and to build a local copy of the UI:

yarn build-all

Adjusting the playbook to include local changes

The Antora build is specified in the camel-website:antora-playbook.yml playbook. The content repositories are specified under the content/sources key. Locate the subproject you are working on and change the url to point to the local checkout of the subproject, e.g.

#    - url: https://github.com/apache/camel-quarkus.git (1)
    - url: ./../camel-quarkus (2)
      branches:
        - main
        - 2.5.x
        - 2.4.x
      start_path: docs
1 Leaving the original can help setting up the playbook for a PR build.
2 This relative path depends on the organization of all your camel projects in a camel directory.

Your local changes will need to be on a branch, so change the branch name, e.g.

#    - url: https://github.com/apache/camel-quarkus.git
    - url: ./../camel-quarkus
      branches:
#        - main
        - main-doc-fixes
        - 2.5.x
        - 2.4.x
      start_path: docs

Make sure that every branch used in the documentation is present locally and up to date. In the subproject directory, for each branch, run e.g.

git switch 2.5.x
git pull

Now you are ready to build your work locally, in camel-website:

yarn build:antora
# or yarn build to include hugo content.

Note that Antora will use the file system state of your main checked-out branch, whether or not these changes are committed. If you have additional git worktrees checked out, you can have Antora use the file system state of these also, see the Antora worktrees documentation.

If you do a full build and have Docker available locally you can view your build served with httpd by running local-httpd-in-docker.sh.

New, renamed, or removed pages

  • Add, rename, or remove the xref for your page in the appropriate nav.adoc file.

  • Build the entire website and check for broken xrefs: these will appear as errors in the Antora log output.

Changed xrefs

First, read A guide to xrefs

  • Build the entire website and check for broken xrefs.

Adding a new component version

See Updating the website after a release.

A guide to xrefs

For a general explanation of Antora xref syntax see the Antora documentation. Due to the logical structure of the Camel documentation, xrefs will have a very limited choice of structure.

A bit of confusion is possible here between Antora components and Camel components. Generally an Antora component corresponds more or less to a Camel subproject, and never to a camel commponent. All the camel components are documented in an Antora component named components. In this section the word component means an Antora component.
Antora components may be distributed which means that the content comes from more than one place, possibly from different repositories. For instance, the components component has content from the main camel repository under the start_paths docs/components and core/camel-core-engine/src/main/docs and from the camel-spring-boot repository under components-starter and docs/components. Furthermore the content may not appear in the normal Antora structure but may be collected from a more maven-project-friendly arrangement with an Antora extension.

xrefs within an (Antora) component

Generally there will never be a reason to refer from one version of a component to another version. To assure this happens without maintenance issues, leave out the version and component segments from the xref, e.g. in the components component

xref:eips:enterprise-integration-patterns.adoc[]

NOT

xref:next@components:eips:enterprise-integration-patterns.adoc[]

Do this no matter how many locations the component is distributed over.

An xref within the same module can leave out the module segment, although it does no harm.

Do not specify the component name: if you do, the link will be to the latest (non-prerelease, i.e., non-next) version, not the current version.

Links to the user manual

The user-manual component is unversioned. Leave out the version segment. For example, this will link to this page from anywhere in the documentation:

xref:manual::improving-the-documentation.adoc[]

Links between subprojects

Each camel subproject relates to other subprojects, and each version of a subproject relates to specific versions of these other subprojects. These subproject versions are specified in the antora.yml component descriptor for the documentation component for that subproject. Note that for distributed components each start path has a component descriptor but only one has the additional asciidoc/attributes key. For example,

name: camel-kafka-connector
title: Camel Kafka Connector
version: next
prerelease: true
display-version: Next (Pre-release)

nav:
- modules/ROOT/nav.adoc

asciidoc:
  attributes:
    camel-version: 3.12.x
    camel-k-runtime-version: 1.8.0
    camel-k-version:
    camel-kamelets-version: 0.3.0
Setting these up is WIP

Use these attributes to refer to documentation for the related subproject, e.g.

xref{blank}:{camel-version}@components:eips:enterprise-integration-patterns.adoc[]

If there’s a missing attribute, please raise an issue rather than using a concrete version.