Contributing to Magnolia Documentation


Thank you for taking the time to contribute to Magnolia documentation. This page guides you through understanding the documentation workflow and contributing directly to the docs.

As of 2022-12-02, contributions are internal only.
A PDF version^ of this document is available.

Clone the repository

The first thing you need to do in order to contribute to the docs is clone the repository.

Git needed

You must have git installed.

  1. Navigate to

  2. Clone the repo.

    1. Under Actions > Clone, choose HTTP since this is a public repository.

      If you want to use SSH, please read the Git SSH tutorial from Atlassian for assistance.
    2. Copy the URL.

    3. From your terminal, type git clone and paste the URL as so:

      git clone
    4. Hit Enter.

      You should see messages similar to the following:

      $ git clone
      Cloning into 'product-docs'...
      remote: Enumerating objects: 1882, done.
      remote: Counting objects: 100% (1882/1882), done.
      remote: Compressing objects: 100% (1751/1751), done.
      remote: Total 22523 (delta 1108), reused 184 (delta 109)
      Receiving objects: 100% (22523/22523), 191.01 MiB | 13.62 MiB/s, done.
      Resolving deltas: 100% (14837/14837), done.
      Updating files: 100% (3756/3756), done.

Repository structure

Go to the /modules folder to see the documentation. The documentation is structured as follows:

├── modules/ (1)
│   └── HOME/ (2)
│   └── ROOT/ (3)
|       └── attachments/ (4)
|       └── images/ (6)
|       └── pages/ (7)
|       └── partials/ (8)
|       └── nav.adoc (9)
├── antora.yml (10)
Item Description

1 modules

The required modules folder. This is where antora looks for the content during a build.


This is a stand-alone module that contains the landing page for the documentation site.


The default module for antora documentation is ROOT.

This can be changed. You can also have as many modules as needed to more easily manage docs.

4 attachments

Stores downloadable files such as pdf, csv, json, jar files, and so on. Anything that needs to be downloaded directly from the documentation website is stored here.

We also store examples in this folder. Typically, examples are stored in an examples directory, but for single-sourcing, we store them here so examples and downloads can be updated and published via the same file.

While updating, a developer also makes changes to the corresponding example.

  • exists in the attachments directory.

  • is used in 3 locations in the documentation with an include directive (xref:attachment$

  • All 3 locations are updated consistently from a single source.

  • To use as a download, the syntax is:


5 images

Contains all images for the documentation. This includes videos and gif files.

6 pages

The deliverable pages for the site.

Typically, pages contain multiple partials set as an assembly. For more information on assemblies, see Redhat’s Modular Documentation.

7 partials

These are reusable bits of information that should be one of the following:

  • concept = labeled with the prefix c as in c_services-cloud-intro.adoc. Explains a concept or description of an item or process.

  • reference = labeled with the prefix r as in r_variables.adoc. Contains reference material such as definitions or variables.

  • procedure = labeled with the prefix p as in p_installing-with-maven.adoc. Guides users with a set of prerequisites and instructions.

For more information on partials as modules, see Redhat’s Modular Documentation.

8 nav.adoc

Establishes the navigation seen on the sidebar for this particular module.

9 antora.yml

Specifies important information for the documentation such as name of the repository, the version, and any potential attributes used throughout the documentation for this module.

antora.yml example
# release-related-page
name: product-docs
title: Magnolia CMS Documentation
version: master
  - modules/ROOT/nav.adoc


After you have successfully cloned the docs repository, you can contribute by adding new files or editing existing asciidoc files.


The first thing you want to do is identify what page you would like to edit. The best way to find the page is to use the URL from the docs site.

Site URL

Page location in repo



This section takes you through the steps to write and submit your work for your review. Writing in asciidoc is simple. Plain text works most of the time.

Check out the Writing toolkit for a crash-course in asciidoc.

If you are using asciidoctor’s include directive, do not add the includable files within the pages directory as antora does not expect this and it will cause the build to fail.

Instead, place the includable file in a partial or if it is a pure code sample, put it in the attachments directory.

From Antora 2.2, there is a page-partial attribute that can be set to override this default behavior. However, we encourage you to stick to the standard route for the time being.

  1. Open your text editor.

  2. Using your integrated terminal or your machine’s terminal, navigate to the local directory where you cloned the doc repo.

  3. Pull down the latest changes by running git pull while on the master branch.

  4. Create a new branch by running git checkout -b <JIRA> using the JIRA ticket as the branch name.

    If you don’t have a JIRA ticket, create one here.
  5. Make your changes.

  6. When ready, add your changes to the branch by running git add . - the full stop adds all local changes.

  7. Commit your changes by running git commit -m "describe the changes".

  8. Push your changes to your remote branch by running git push origin <JIRA>.

  9. Go to

  10. Create a Pull Request.

    See Making a pull request for more details.
  11. Add one of the doc team members for review.

  12. Switch back to the master branch by running git checkout master.

  13. Make sure that any new updates are included by running git pull.


The review process follows a typical software development cycle flow. After the Pull Request is created and you have assigned reviewers, reviewers can comment, assign tasks, approve, and reject the request.

The Magnolia documentation team maintains the site and has the final say on merging the content into the official product documentation.

Contribution templates

Currently, there are templates for writing modules and release notes.

See the product-docs-templates repo for these templates.

Site build

The content in this repository is fetched via the playbook (1 below) in the antora build we have set up for Magnolia documentation.

  title: Magnolia CMS Docs
  # the 404 page and sitemap files only get generated when the url property is set


  edit_url: ~
  - url: (1)
    branches: [master]
#   start_path: docs

View your changes locally

While building the site locally is a great way to see changes, the documentation team are able to view your pull request locally when we review.

In light of this, you should only build the site locally if you have the following installed and are accustomed to using them:

  1. Clone the antora site repo.

  2. Cd to the root of the repo.

  3. Run npm install.

  4. Copy the content from playbook.yaml.

  5. Create a new file called local-playbook.yaml.

  6. Paste the content from playbook.yaml into local-playbook.yaml.

  7. In local-playbook.yaml, under content, adjust the values for the sources:

    Local Playbook
      - url: ../product-docs (1)
        branches: HEAD (2)
    #   start_path: docs (3)
        edit_url: false
    1 url Point the playbook to the local path that holds your product-docs repo. Set the url as the path relative to your local antora site repository.
    2 branches Set it to HEAD. This ignores the worktree and shows you content from whatever branch you’re on.
    3 start_path: docs Uncomment this line if the documentation is to be build from a repository other than product-docs. For example, from your local clone of a Magnolia module repository such as javascript-models or from a product branch repo such as magnolia-cloud. (NOTE: Not all Magnolia module pages have their docs stored in the dev repos outside product-docs. Always check this before contributing to a module page.)
  8. Under output, point the dir property to a path with an existing local folder where Antora will export the site files:

      dir: ./local-build
  9. Run npx antora local-playbook.yaml.

  10. To see the local docs build, open ./local-build/index.html from the local-build folder.

It’s best to make an alias or script to run this. See Creating bash aliases for more details.

For example

I have an alias named local that navigates to my antora-site folder, runs the local playbook, and then opens the output in my browser as shown below:

alias local="cd /c/Users/aubur/Documents/Magnolia/docs-as-code/antora-site/; antora local-playbook.yaml; start chrome local-build/index.html"
Why not just use the build/site folder?

As a precaution, it’s usually best practice to avoid rebuilding into this directory with local changes.

Build environments

There is both a staging and production environment for Magnolia Documentation. We use S3, AWS, and the documentation toolchain to produce this. Every pull request triggers a staging build.

I want to learn more

See the asciidoctor and antora official sites for more information on these tools.

Reporting an error or bug

You can report errors, doc bugs, and enhancements for Magnolia documentation using the Feedback button found on the right side of the documentation site as shown below. This takes you to the DOCU Jira project for Magnolia where you can submit your request.

feedback button on Magnolia Documentation website
DOCU ticket tips
Use a clear and descriptive title

For example, “Installing Magnolia provides the wrong minimum Java version”

Describe the problem or enhancement in full

Describe the issue in detail, including any expected results and how they differ from the actual results. The documentation team are not necessarily experts in all aspects of Magnolia. Providing a detailed description along with expected results will greatly reduce the turnaround time.