Contributing to Magnolia Documentation
Introduction
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 2021-04-09, 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.
-
Navigate to https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/product-docs/.
-
Clone the repo.
-
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. -
Copy the URL.
-
From your terminal, type
git clone
and paste the https://git.magnolia-cms.com/scm/documentation/product-docs.git URL as so:git clone https://git.magnolia-cms.com/scm/documentation/product-docs.git
-
Hit Enter.
You should see messages similar to the following:
$ git clone https://git.magnolia-cms.com/scm/documentation/product-docs.git 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)
| └── examples/ (5)
| └── images/ (6)
| └── pages/ (7)
| └── partials/ (8)
| └── nav.adoc (9)
├── antora.yml (10)
└──
Item | Description | ||
---|---|---|---|
1 |
The required |
||
2 |
This is a stand-alone module that contains the landing page for the documentation site. |
||
3 |
The default module for antora documentation is
|
||
4 |
Stores downloadable files such as pdf, csv, json, jar files, and so on. Anything that needs to be downloaded directly from the documentation website. |
||
5 |
This is typically used for code samples and where developers can directly either add or build triggers to pull information directly into the docs. Example 1. Example
While updating
|
||
6 |
Contains all images for the documentation. This includes videos and gif files. |
||
7 |
The deliverable pages for the site.
|
||
8 |
These are reusable bits of information that should be one of the following:
|
||
9 |
Establishes the navigation seen on the sidebar for this particular module. |
||
10 |
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
|
Contribute
After you have successfully cloned the docs repository, you can contribute by adding new files or editing existing asciidoc files.
Prerequisites
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.
|
Write
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. You can refer to the Helpers file for tips on using and asciidoc and see the official Asciidoctor site for more advanced uses. |
-
Open your text editor.
-
Using your integrated terminal or your machine’s terminal, navigate to the local directory where you cloned the doc repo.
-
Pull down the latest changes by running
git pull
while on themaster
branch. -
Create a new branch by running
git checkout -b <JIRA>
using the JIRA ticket as the branch name. -
Make your changes.
-
When ready, add your changes to the branch by running
git add .
- the full stop adds all local changes. -
Commit your changes by running
git commit -m "describe the changes"
. -
Push your changes to your remote branch by running
git push origin <JIRA>
. -
Go to https://git.magnolia-cms.com/projects/DOCUMENTATION/repos/product-docs/.
-
Create a Pull Request.
See Making a pull request for more details. -
Add one of the doc team members for review. Currently, those are Julie Legendre, Ashraf Khamis, Martin Drápela, Alex Mansell.
Review
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.
site:
title: Magnolia CMS Docs
# the 404 page and sitemap files only get generated when the url property is set
url: https://docs.magnolia-cms.com/product-docs/
...
content:
edit_url: ~
sources:
...
- url: https://git.magnolia-cms.com/scm/documentation/product-docs.git (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: |
-
Clone the antora site repo.
-
Run
npm install
. -
Cd into the
ui
folder. -
Run
npm install
. -
Run
gulp bundle
. -
Cd back to the root folder.
-
Copy the content from
playbook.yaml
. -
Create a new file called
local-playbook.yaml
. -
Paste the content from
playbook.yaml
intolocal-playbook.yaml
. -
Under content > sources in your
local-playbook.yaml
file, 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.
-
For
branches:
, set it toHEAD
. This ignores the worktree and shows you content from whatever branch you’re on.Local Playbookcontent: sources: - url: ../product-docs (11) branches: HEAD (12) edit_url: false
-
Under output in your
local-playbook.yaml
file:output: dir: ./local-build
-
Run
antora local-playbook.yaml
and open./local-build/index.html
from thelocal-build
folder.
It’s best to make an alias or script to run this. For me (Alex - on Windows), I have created an alias called For example:
I have an alias named
|
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.
- 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.
