Antora

Mapping to content repositories

Each content source repository will typically define a single component. It is possible to use multiple repositories for a single component.

Setting up component repositories

If a repository contains documentation for only one component, it is sufficient to use for instance the /docs/ directory as the root of a component.

In many cases, however, we have multiple components under the /docs/ directory. Each of these will have its own antora.yml to define the component to which it contributes.

Merging multiple repositories for a component

For instance, it is possible to add private documentation to a section or module in two ways. Each has its own workflow. I’m not sure yet which version works best, or whether it depends on the context of use.

Main problem with "injection" is that there can only be one list of navigation docs.

It would require separate "public" and "private" versions of the component definition, with their own nav lists.

Work with a private branch, and use this to add private documentation to the existing documentation.
- This makes the documentation structure easier to manage, and it is possible to add private notes to public pages.
- It would benefit from clearly marking the private portions, especially in the sources.
- It requires additional work to port updates of public documentation into the public branch.
- It may be best suited for deployment-specific branches, to create deployment-specific documentation that includes configuration code.
Work with a separate folder for additional private documentation.
- This works for modules and pages.
- It is not possible to add private notes to existing pages.
- It keeps the private sections clearly separated from public sources, reducing the chances of accidental publishing.
- It would also benefit from clearly marking the private portions, but more for the front-end.

Repositories and folder structure

Local repositories
├── localhost
|   ├── antora-playbooks
|   |   ├── private.yml
|   |   ├── lib-antora.yml
|   |   └── lib-hop.yml
|   └── docs
|       └── private
|           ├── modules/
|           └── antora.yml
├── public site
|   ├── playbook-docs.yml
|   └── docs
|       ├── overview
|       |   ├── modules/
|       |   └── antora.yml
|       └── documentation_system
|           ├── modules/
|           └── antora.yml
├── my antora ui
|   ├── docs
|   |   ├── modules/
|   |   └── antora.yml
|   └── my_docs
|       ├── modules/
|       └── antora.yml
└── desktop config
    └── docs
        └── modules/
            ├── modules/
            └── antora.yml