Contributing to the Mautic documentation

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 git
Why Grav
How to contribute
- Editing documentation using the command line
- Editing documents in the GitHub browser interface
File Structure
Style Guide
Mautic specific information

Why `git`

Why is git used for the documentation

versions - anyone can go back and look at what the text looked like.
authorship - not only every file, but every line has its author.
community contributions - no need to worry about deleting someone else's work while working on the same document.

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.

Why Grav

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.

How to contribute

Using Grav

Create a Mautic Community login, or log in with your existing forum/website account at the login page
Send a message in the Documentation slack channel to have your account raised to 'editor' - get a Slack invite here
When logged in, click on the 'Edit page in Grav' link on the relevant page and make your changes

Using Github

Fork this repository at GitHub
Select a file to edit on your fork
Make your commits
Open a pull request to base fork: mautic/documentation with base: master
Include and reference any Issues your Pull Request addresses

Editing documentation using the command line

In the command line cd to where you want the documentation repository located

Clone this repository

git clone https://github.com/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 your editor of 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
- Direct link: https://github.com/{yourusername}/mautic-documentation/pull/new/{yourusername}-revision-readme-file
- GitHub web interface - base fork: mautic/documentation and base: master at GitHub
- use the hub utility
```
hub pull-request
```

Editing documents in the GitHub browser interface

Note
If you're unfamiliar with the command line but still want to contribute to the Mautic documentation

Using README.md as an example:

Fork this repository under your account so you'll have permission to edit.
Select the README.md file (refer to the file structure section below if needed)
With the content of README.md visible, click on the pencil icon to begin editing the file
The .md extension means this file was written in Markdown, a simple but flexible text formatting language. Mautic documentation is written with Markdown markup specifically.
After you've made a change, scroll down to the Commit changes form. Saving your change requires describing what was changed and why.
Before submitting your commit, select the box for Creates a new branch to start a new branch for your change. Name your branch something like {yourusername}-revision-readme-file
Select Propose file change
In the next dialogue box, describe what you've changed and why then select Create pull request to open a pull request proposing we add your changes to our official repository.

File Structure

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.

Style Guide

The style guide section is very much a 🚧 Work in Progress.

Please contribute :)

Whitespace and spaces

One blank line around headings
One blank line around list items
One blank line around code blocks
One final blank line
Two spaces after a full stop. Next sentence.

Lists

Use 1. for numbered lists.
Use 1. only for numbered lists.
Use - for unnumbered lists
- Indent spaces until first character of content in line above
- which is effectively 2 spaces for nested unnumbered lists

example list

Example nested list

Item the first
Something else
1. indent spaces until first character of content in line above
2. that means line up on the S in Something
  1. and the first t in that
And finally
- minor point from the A

not part of the numbered list

markdown syntax

Nested list markdown syntax

1. Item the first
1. Something else
   1. indent spaces until first character of content in line above
   1. that means line up on the `S` in `Something`
      1. and the first `t` in `that`
1. And finally
   - minor point from the `A`

- not part of the numbered list

Code blocks

Prefer fenced <codeblock>s with three backticks
Must have language identifier
- Use text if no highlighting required
Fenced code blocks within lists need to be indented for numbered lists to continue

example codeblock

Example `<codeblock>`

/**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}

A markdown syntax

`<codeblock>` markdown syntax

/**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}

example nested codeblock

Example nested `<codeblock>`

START list item

Example nested <codeblock>

/**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}

END list item

markdown syntax

Nested `<codeblock>` markdown syntax

    ```php
    /**
     * Constructor.
     *
     * @param string $environment The environment
     * @param bool   $debug       Whether to enable debugging or not
     *
     * @api
     */
    public function __construct($environment, $debug)
    {
        defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
        defined('MAUTIC_VERSION') or define(
            'MAUTIC_VERSION',
            self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
        );

        parent::__construct($environment, $debug);
    }
    ```

Links

Often 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:

Absolute links

Aut et laudantium ad ratione id. Ut similique quis et ut. Consectetur eum quia totam recusandae necessitatibus dolorem debitis.

Aut et laudantium ad [ratione id][link macro]. Ut similique quis et ut.
Consectetur eum quia totam [recusandae][link macro] necessitatibus dolorem debitis.

[link macro]: <http://example.com>

Relative links

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

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.

Aut et laudantium ad [ratione id](#heading-anchors). Ut similique quis et ut.
Consectetur eum quia totam [recusandae](#style-guide) necessitatibus dolorem debitis.

Images

Images should be placed in the media subfolders in the different sections of this repository.

Link format:

![alternative text here](image-reference.png "Tooltip text here")

relative image links

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.

![form rebuild cache](media/rebuild.png "Rebuild form cache"")

![form rebuild cache](./../forms/media/rebuild.png "Rebuild form cache")

absolute image links

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

![apple](http://example.com/images/apple.png "Like this delicious apple")

Warning

internal absolute image link

This link format should NOT be used.

~~![form rebuild cache](/forms/media/rebuild.png "Rebuild form cache")~~

Mautic specific information

Example domain references

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
```

Protocol scheme: http vs https

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
```

Linking to Release versions

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.
- A <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` version

Avoid 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>

References to leads and lead lists

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

In Mautic version 1.4,

leads were renamed to contacts

lead lists were renamed to segments

anonymous leads were renamed to visitors

markdown syntax

reference note

> **Note**
>
> In this document, there may be references to outdated terminology such as
>
> - _leads_,
> - _lists_ or _lead lists_, and
> - _anonymous leads_
>
> In [Mautic version `1.4`][release-1.4.0],
>
> - _leads_ were renamed to _**contacts**_
> - _lead lists_ were renamed to _**segments**_
> - _anonymous leads_ were renamed to _**visitors**_

[release-1.4.0]: <https://github.com/mautic/mautic/releases/tag/1.4.0>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing to the Mautic documentation

Why `git`

Why Grav

How to contribute

Using Grav

Using Github

Editing documentation using the command line

Editing documents in the GitHub browser interface

File Structure

Style Guide

Whitespace and spaces

Lists

Example nested list

Nested list markdown syntax

Code blocks

Example `<codeblock>`

`<codeblock>` markdown syntax

Example nested `<codeblock>`

Nested `<codeblock>` markdown syntax

Links

Absolute links

Relative links

Heading anchors

Images

relative image links

absolute image links

internal absolute image link

Mautic specific information

Example domain references

Protocol scheme: http vs https

Linking to Release versions

`latest` version

References to leads and lead lists

reference note

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to the Mautic documentation

Why git

Why Grav

How to contribute

Using Grav

Using Github

Editing documentation using the command line

Editing documents in the GitHub browser interface

File Structure

Style Guide

Whitespace and spaces

Lists

Example nested list

Nested list markdown syntax

Code blocks

Example <codeblock>

<codeblock> markdown syntax

Example nested <codeblock>

Nested <codeblock> markdown syntax

Links

Absolute links

Relative links

Heading anchors

Images

relative image links

absolute image links

internal absolute image link

Mautic specific information

Example domain references

Protocol scheme: http vs https

Linking to Release versions

latest version

References to leads and lead lists

reference note

Why `git`

Example `<codeblock>`

`<codeblock>` markdown syntax

Example nested `<codeblock>`

Nested `<codeblock>` markdown syntax

`latest` version