Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
340 lines (231 sloc) 11.7 KB

Contributing to the Mautic documentation

This Gitbook 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 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. If you know git, use the workflow you like. If not, the following guide will show you how to contribute easily.

How to contribute

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

Editing documentation using the command line

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

  2. Clone this repository

    git clone https://github.com/mautic/documentation.git --origin upstream
  3. Fork this repository at GitHub or use the hub utility

    hub fork --remote-name origin
  4. Once cloning has completed, open the project in your editor of choice

  5. 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
  6. Make your changes

  7. 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'
  8. Push to origin

    git push origin
  9. Review the changes at your fork https://github.com/{yourusername}/mautic-documentation

  10. 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:

  1. Fork this repository under your account so you'll have permission to edit.
  2. Select the README.md file (refer to the file structure section below if needed)
  3. With the content of README.md visible, click on the pencil icon to begin editing the file
  4. 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.
  5. After you've made a change, scroll down to the Commit changes form. Saving your change requires describing what was changed and why.
  6. 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
  7. Select Propose file change
  8. 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.

Code blocks

  1. prefer fenced codeblocks with three backticks

  2. fenced code blocks within lists need to be indented for numbered lists to continue

    <?php
    
    /*
    * @copyright   2014 Mautic Contributors. All rights reserved
    * @author      Mautic
  3. must have language identifier

    • use text if no highlighting required

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 nested unnumbered lists
markdown
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 now the `t` in `that`
1. And finally
   - minor point from the `A`
- not a number
result
  1. Item the first
  2. 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 now the t in that
  3. And finally
    • minor point from the A
  • not a number

Example domain references

Please use example.com as the reference domain for documentation.

Standard Mautic URL example

https://example.com

Mautic as subdomain URL example

https://mautic.example.com

Mautic as subdirectory URL example

https://example.com/mautic

http vs https URL example

Prefer the https:// protocol in documentation. We want to promote good practices.

https://example.com

If you need to show both protocols, add brackets around the (s)

http(s)://example.com

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][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.

[integration test]: <integration_test.html>

[integration test]: <./../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")
internal absolute image link

Warning

This link format should not be used.

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

Linking to Release versions

Use an absolute external link to reference the official released versions of Mautic. Include Mautic and the version number in the link macro. All version numbers have 3 components: <major>.<minor>.<patch>

Since [Mautic 2.9][release-2.9.0], when...

[release-2.9.0]: <https://github.com/mautic/mautic/releases/tag/2.9.0>
You can’t perform that action at this time.