Mautic is an Open Source marketing automation platform. We welcome contributions to improve and maintain our documentation.
Mautic is made up of over 39 Git repositories. To contribute to the Mautic User guide, you must fork the mautic-documentation Git repository. You can also contribute to the Developer documentation by forking the developer-documentation Git repository.
Although we support using both GitHub and Grav for making changes to the documentation, we'd prefer contributions using GitHub for the following reasons:
You might require some knowledge of Git to clone, modify, commit, and push changes. However, there is a way to avoid that and edit the files directly in the GitHub web interface or via our web-based interface using the Grav CMS. To learn how to contribute using GitHub, see Using GitHub. If not, you can contribute easily using Grav.
If you intend to make any changes to the documentation, we recommend filing an issue. This allows us to reach an agreement on your proposal before you put significant effort into it. To report new issues or fix existing issues, visit the Mautic Documentation Issues page on GitHub.
A great place to start and familiarize yourself with our contribution process is to take a look at the list of good first issues
that we have earmarked for new contributors. These issues have a relatively limited scope.
If you wish to fix an issue, please check the comment thread to ensure that no one else is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it to avoid any accidental duplication of your effort.
The Mautic documentation repository consists of the following files and folders:
The README.md
file serves as the introduction and description of this repository. This file does not contain any product documentation.
The folders in this repository are grouped together by topics.
pages
folder contains folders for each chapter in the Mautic user guide. Each folder contains .md files (one per language - currently English only) that you can edit along with images used in this page. For example, within the Campaigns folder, you'll sub-folders for subtopics such as Managing Campaigns, Campaign Events, etc. Each of these folders contain its own docs.en.md
file and all images used in the .md files. plugins
folder contains folders for each plugin that Mautic offers.themes
folder contains all the themes available for this repository. Each folder contains supporting files for a separate theme.For keeping contributions consistent, we encourage you to read our Style Guide which is a set of conventions that we follow while writing documentation for Mautic. You can find our Style Guide here.
Mautic documentation is written with Markdown markup, a simple but flexible text formatting language. The Markdown files are appended with the .md extension.
Previously GitBook was used to manage the Mautic documentation. However, this became cumbersome to maintain and difficult for those who were not familiar with Git. After exploring various solutions, the Education Team decided that Grav would best meet the needs of the Community.
base fork: mautic/mautic-documentation
with base: master
.If you want to edit documents using the Git command-line system, read this section. You can also use the GitHub CLI utility that makes working at the command line easy.
In the command-line cd
to where you want the documentation repository to be located.
Clone this repository.
git clone https://github.com/mautic/mautic-documentation.git --origin upstream
Fork this repository at GitHub or use the hub
utility.
hub fork --remote-name origin
Once cloning has completed, open the project in the editor of your choice.
Create a new branch for your edits. Please name your branch something descriptive like {yourusername}-revision-readme-file
git checkout -b {yourusername}-revision-readme-file upstream/master
Make your changes.
Stage and commit your changes to your local repository.
git status --short
git add <new and modified files>
git commit --message 'move contributing to new file'
Push to origin
.
git push origin
Review the changes at your fork -https://github.com/{yourusername}/mautic-documentation
.
Submit your pull request using one of these methods:
https://github.com/{yourusername}/mautic-documentation/pull/new/{yourusername}-revision-readme-file
base fork: mautic/mautic-documentation
and base: master
at GitHubhub
utilityhub pull-request
If you're unfamiliar with the Git command-line but still want to contribute to the Mautic documentation via GitHub, read this section.
Using README.md as an example:
{yourusername}-revision-readme-file
Note: If you are updating more than one file, then you can select the newly created branch to switch to the branch, and then repeat this process until you have made all the required edits, before creating a pull request.
Use example.com
as the reference domain for documentation.
For the various installation types, use
standard Mautic URL example
https://example.com
include www
if relevant
https://www.example.com
Mautic installed as subdomain URL
https://mautic.example.com
Mautic installed as subdirectory URL
https://example.com/mautic
Prefer the https://
protocol in documentation.
https://example.com
If you need to show both protocols, add brackets around the (s)
http(s)://example.com
Use an absolute external link to reference the official released versions of Mautic. The project adheres to Semantic Versioning, so all version numbers have three components: <MAJOR>.<MINOR>.<PATCH>
Prefix the version with the word Mautic
in the text, and the full three-part version number in the link macro.
<MAJOR>.<MINOR>
release version without <PATCHES>
may be used in the text, but still use the full three-part version number in the link.Wrapping the version number in <code>
backticks "`" is optional.
Since Mautic
2.9
, when...
Since [Mautic `2.9`][release-2.9.0], when...
[release-2.9.0]: <https://github.com/mautic/mautic/releases/tag/2.9.0>
latest
versionAvoid using the term current
or latest
if you actually mean _"the currently released version of Mautic that I installed."
In most cases, it has no meaning when a new version is released. Instead, check the latest release and explicitly use that version number.
Do NOT do this:
In
the...latest
version of Mautic
DO this instead:
In Mautic
2.15.3
...
> In [Mautic `2.15.3`][release-2.15.3] ...
[release-2.15.3]: <https://github.com/mautic/mautic/releases/tag/2.15.3>
Include this Note if there are references to outdated terminology that cannot be updated.
Note
In this document, there may be references to outdated terminology such as
- leads,
- lists or lead lists, and
- anonymous leads
- leads were renamed to contacts
- lead lists were renamed to segments
- anonymous leads were renamed to visitors
Found errors? Think you can improve this documentation? edit this page