Mattermost Documentation

This repository generates the documentation available at https://docs.mattermost.com/. All documentation is available under the terms of a Creative Commons License.

If you have any questions, create an account on the Mattermost Community server, then join the writing team in the Documentation Working Group channel. We look forward to working with you!

Table of Contents

• Contributing
  • Get started
  • Edit content directly on GitHub
  • Create documentation PRs
  • Use GitHub PR Labels
  • Comment on Pull Requests
  • Review Pull Requests
• Build locally

Contribute to Mattermost product documentation

Get started

You can edit or create Mattermost documentation directly in GitHub, or by downloading the mattermost/docs repository onto your machine and using an IDE such as VS Code. Consult the Mattermost Documentation Style Guide and reStructuredText Markup section for stylistic and technical guidance.

If this is your first time contributing to Mattermost, first read and sign the Mattermost Contributor Agreement, so you can be added to the Mattermost Approved Contributor List.

Edit content directly on GitHub

The quickest way to begin is editing directly on GitHub on your fork of the Mattermost docs repo. Select the Edit icon on the top right corner of the page you want to edit in the Mattermost documentation.

If this is the first time you're contributing, follow these steps:

1. Select Fork in the top-right corner of the GitHub repository page to fork the current repository.
2. Navigate to file you want to edit, then select the Pencil icon (Edit the file) to open the editing interface.

Create Documentation pull requests

1. When you're ready to submit your changes, add a descriptive title and comments to summarize the changes made.
2. Select Create a new branch for this commit and start a pull request.
3. Check the Propose file change button.
4. Scroll down to compare changes with the original document.
5. Select Create pull request.

Use GitHub PR labels

GitHub PR labels are used to track the life cycle and status of a pull request. Using the correct labels helps with managing workflows and ensuring that content is edited, merged and released at the correct time. For example, PRs that include an Editor Review label will be processed by an editor on the writing team to ensure the documentation is correctly formatted at https://docs.mattermost.com/ based on guidelines outlined in the style guide.

Take a look at the Labels page for information about how and when to use which labels.

Comment on pull requests

Once a pull request is submitted, multiple committers may comment on it and provide edits or suggestions which you can commit directly. You can also add line comments. Take a look at Commenting on pull requests for more details.

Review pull requests

Once a pull request has been submitted and the correct label assigned, the review process begins. This includes aligning the content with the Style Guide, validating processes, and tagging any other relevant committers. Read more about the review process and expectations in the Mattermost Developer documentation.

Once the review process is complete, and depending on the type of issue it is (e.g., a typo fix vs. a new feature), the change is either merged into master and pushed immediately or merged into the release branch and pushed in alignment with a future release. The branch is then deleted.

Build locally

If you've downloaded the mattermost/docs repository to edit Mattermost documentation on your local machine, you can generate the HTML files from the source directory. You can review your changes as a live or static preview before committing them or creating new pull requests.

Note

You can generate the docs on Linux, Mac, and Windows (using PowerShell); however, builds on Windows are considerably slower because only a single processing core is used.

For faster local docs builds on Windows, we strongly recommend installing WSL to create an Ubuntu virtual machine (VM), where you'll configure the following prerequisites. An Ubuntu VM will use all available processing cores, resulting in faster local builds.

Build prerequisites

The following software is required to build the documentation:

• Git [download]
• Python 3.9 or later [download]
• Pipenv [download]

Build instructions

1. Open a native or VM terminal window, then clone a forked copy of the documentation repository:

   git clone https://github.com/mattermost/docs.git

2. In the terminal window, navigate into the cloned repository:

   cd docs

3. Install pipenv by using one of the following commands based on your operating system:

   For Mac users and Ubuntu VM users where Homebrew is installed:

   brew install pipenv

   For other operating systems:

   pip install --user pipenv

4. Install required Python packages:

   pipenv install --dev

5. Build the documentation set. You have three build commands available at the terminal:

   • Use make html to generate HTML files in the /build directory. Only file you've modified are re-built.
   • Use make clean html to delete all static HTML output in the /build directory and re-build all files. This command is particularly useful when you're making changes to the LHS navigation pane and want to ensure you're not reviewing cached results.
   • Use make livehtml to review a live preview published to http://127.0.0.1:8000 that automatically updates as new changes are saved in your local IDE.

Note

Windows users who aren't building the docs in an Ubuntu VM also require make installed for the build commands above to work correctly. To install make via Chocolatey:

1. Install chocolatey.
2. In a Windows terminal, select the downward chevron, and hold CTRL while selecting PowerShell to run commands as an admin.
3. Accept the admin prompt.
4. Run the following command: choco install make
5. Exit the terminal.

If make isn't installed, substitute CMD /C make.bat for make in the build commands above to use the Windows command interpreter. For example, to run make html, run the command: CMD /C make.bat html. Only a single target may be specified using this method. This means that, instead of running CMD /C make.bat clean html, each target must be run separately as CMD /C make.bat clean followed by CMD /C make.bat html.

When building the Mattermost Product Documentation locally, Windows users will see slower build speeds because only a single processing core is used to build the docs. Mac & Linux users will see faster build speeds because multiple cores are used to build. It's not yet clear where to make changes to support multiple processing cores on Windows machines. More investigation is needed.

6. When working with static build results, navigate to the build directory:

   cd build

7. Then, preview your changes by opening the build/html/index.html file.

Build errors are written to the build/warnings.log file.