This repository serves as the documentation for Mautic, the open source marketing automation system.
Everyone is welcome to contribute to improve this information as needed.
Why is Git used for the documentation?
Although some Git knowledge is required to clone, modify, commit and push changes, 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. If you know Git, use the workflow you like. If not, the following guide will show you how to contribute easily.
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. The Education Team looked into various solutions and decided that Grav would best meet the needs of the Community.
base fork: mautic/mautic-documentation
with base: master
cd
to where you want the documentation repository locatedClone 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
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
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
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
Note: Useful if you're unfamiliar with the command line but still want to contribute to the Mautic documentation via Github
Using README.md as an example:
{yourusername}-revision-readme-file
The README.md
file serves as the introduction and description of this repository. This file does not contain any product documentation.
The SUMMARY.md
file defines the menu of the documentation. If you add a new page to the documentation, you'll have to also add a new line there defining the title and the link to the file (formatted like the existing menu items).
The folders in this repository are grouped together by topic. For example, within the asset folder, you'll see it has its own README.md
file (becomes ./index.html
) which contains the primary description of the Asset menu; the manage_assets.md file is a subitem; the media subfolder contains all the images used in the .md files.
The style guide section is very much a :construction: Work in Progress.
Please contribute :)
One final blank line
1.
for numbered lists.1.
only for numbered lists.-
for unnumbered lists <codeblock>
s with three backtickstext
if no highlighting requiredOften you'll want to make a link to another place in the documentation. We prefer to group links at the bottom of a page, and provide a reference macro in the text. This make linking to the same place much easier. In Markdown, it looks like this:
You can have different links in your text, some leading here and others leading there.
You can have different links in your text, some leading [here][link macro] and others leading [there][link macro].
[link macro]: <http://example.com>
These will link to plugins/integration_test.html
on the documentation website created from the _plugins/integration_test.md
_ source file.
The first line is an example from within the same section. The second for anywhere else in the directory structure.
[testing]: <integration_test.html>
[testing]: <./../plugins/integration_test.html>
Heading anchors enable linking directly to a Markdown heading from within the same document very easily. The anchors are auto-generated for all headings. The link target is specified inline.
You can have different anchors in your text, for example to this [Section][#anchor-section] right here.
### Images
Images should be placed in the media subfolders in the different sections of this repository.
Link format:
```markdown

To display an image already in the documentation repository, use a relative path.
The first line is an example of using images in the same section. The second for anywhere else in the directory structure.


For images that cannot be uploaded via the GitHub web interface, upload them to a public URL service and use the generated link.

Warning
internal absolute image link
This link format should NOT be used.

You can embed a YouTube video using the following syntax: [plugin:youtube](https://www.youtube.com/watch?v=<videoid>)
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>
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.<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 on Github