Contribute to Incubator docs

This page guides you on how to contribute to Incubator module documentation.

Prerequisites

You must have:

  • a text editor or IDE (such as Atom, IntelliJ, or VS Code).

  • access to the Incubator module repo to which you want to contribute

  • git

Structure

Antora structure

The Incubator module docs are built with Antora. Antora is a static-site generator for asciidoc. Antora is quite opinionated when it comes to where the docs live as it fetches from multiple repositories to build the site.

Because of this, you’ll see the docs are embedded in developer repos all in the same structure as shown below.

diagram

Docs structure

The Incubator module docs are generally structured the same way within the /docs/ folder.

diagram
Figure 1. Repo structure
index.adoc
= {page-component-title} (1)

// module overview
include::partial$c_module-overview.adoc[tag="noTitle"] (2)

// install with maven
include::partial$r_install-with-maven.adoc[leveloffset=+1] (2)

// use the module
include::partial$r_usage.adoc[leveloffset=+1] (2)

// integrate the module
include::partial$p_integrate.adoc[leveloffset=+1] (2)

// changelog
include::partial$r_changelog.adoc[leveloffset=+1] (2)
1 The page-component-title is a global variable that takes the title attribute from the antora.yml file.
2 The include directives pull the partials in so you can edit smaller chunks of information.
This also helps keep all incubator module docs as close to the same structure as possible. Note that not all incubator module docs will match this pattern exactly.

antora.yml

The antora.yml file contains important information for building the Incubator module docs.

Typically, you don’t need to edit much of this information except for when the module version is changed. 
name: webhooks
title: Webhooks module (1)
version: master
nav:
 - modules/ROOT/nav.adoc

asciidoc:
  attributes:
    magnolia: https://www.magnolia-cms.com/
    group-id: info.magnolia.workflow (2)
    artifact-id: magnolia-webhooks-integration (3)
    modules-version: 1.0.1 (4)
    version-compatible: '6.2.2' (5)
    jira-project: WEBHOOK (6)
    git: https://git.magnolia-cms.com/projects/INCUBATOR/repos/webhooks/browse (7)
    page-layout: default
1 The page-component-title that is used for the name of the index.adoc file.
2 The group-id when installing with maven.
3 The artifact-id when installing with maven.
4 The version when installing with maven.
5 Lists the Magnolia versions with which the module is compatible.
6 The jira project related to the module.
7 The git repo where the module lives.

Using asciidoc

For tips on using asciidoc, you can check out Magnolia’s Writing toolkit or Asciidoc’s official manual.

Example workflow

In this example workflow, you’ll make a pretend change to the Webhook incubator module.

Before you update any files, you must have cloned the desired incubator module.
Example task

You have been tasked with updating the Webhooks module to be compatible with Magnolia 6.2.42. This involves some development and you need to uprev the module version.

You must update the module version and compatibility version for this module.

Locate the doc file

While looking at the Webhooks module documentation, you can see that the latest version is listed at the top of the page as well as in the Installing with Maven section.

We know that all Incubator module documentation folders have an index.adoc file that contains multiple partials. Let’s locate the content.

Locate the source
= {page-component-title}

// module overview
include::partial$c_module-overview.adoc[tag="noTitle"] (1)

// install with maven
include::partial$r_install-with-maven.adoc[leveloffset=+1] (2)
1 The module overview partial contains the overview information (including compatibility with Magnolia).
2 The installing with maven partial contains the snippet for the pom.xml file.

When you look into those partial files (/modules/ROOT/partials/*.adoc), you see that the module version (modules-version) and compatibility versions (version-compatible) are variables. you know this as they wrapped with curly braces {}.

Update the doc file

First, create a new branch for your changes:

git checkout -b <branch-name>

Variables are in the antora.yml file, so you simply need to update that file to make the change you need:

antora.yml
name: webhooks
title: Webhooks module
version: master
nav:
 - modules/ROOT/nav.adoc

asciidoc:
  attributes:
    magnolia: https://www.magnolia-cms.com/
    group-id: info.magnolia.workflow
    artifact-id: magnolia-webhooks-integration
    modules-version: 1.0.1  (1)
    version-compatible: '6.2.2' (2)
    jira-project: WEBHOOK
    git: https://git.magnolia-cms.com/projects/INCUBATOR/repos/webhooks/browse
    page-layout: default
1 Update the module version and this is picked up wherever it is placed in the .adoc files.
2 Update the compatible versions and this is reflected where it is placed in the .adoc files.

Preview changes

You can preview your changes with your local asciidoc preview renderer.

Typically, there are keyboard shortcuts to toggle the preview. For example, ctrl+k v opens the preview to the side my current .adoc file when using VS Code.

The shortcut will vary depending on your setup.

If you want to build the whole site locally to see your changes, follow the instructions here.

Push changes

Now that you have updated the file and previewed your changes, push the changes to the Incubator module repository.

git add docs/; git commit -m "updated the documentation"; git push origin <branch-name>;
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Incubator Modules docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules