Table of Contents
- Build Mattermost product documentation locally
Contribute to Mattermost product documentation
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.
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:
- Select Fork in the top-right corner of the GitHub repository page to fork the current repository.
- Navigate to file you want to edit, then select the Pencil icon (Edit the file) to open the editing interface.
Create Documentation pull requests
- When you're ready to submit your changes, add a descriptive title and comments to summarize the changes made.
- Select Create a new branch for this commit and start a pull request.
- Check the Propose file change button.
- Scroll down to compare changes with the original document.
- Select Create pull request.
Use GitHub PR labels
GitHub PR labels are used to track the lifecycle 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.
If you've downloaded the
mattermost/docs repository and are editing Mattermost documentation on your local machine, you can generate the HTML files from markdown in the
/source directory. You can review your changes before you commit them or create pull requests.
Note: Terminal commands can be executed on Linux, Mac, and Windows (using Powershell).
Open a terminal window, then clone a forked copy of the documentation repository:
git clone https://github.com/mattermost/docs.git
In the terminal window, navigate into the cloned repository:
Install pipenv by using one of the following commands based on your operating system:
For Mac users where Homebrew is installed:
brew install pipenv
For other operating systems:
pip install --user pipenv
Install required Python packages:
pipenv install --dev
Build the documentation set. You have three build commands available at the terminal:
make htmlto generate HTML files in the
/builddirectory. Only file you've modified are re-built.
make clean htmlto delete all static HTML output in the
/builddirectory 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.
make livehtmlto review a live preview published to
http://127.0.0.1:8000that automatically updates as new changes are saved in your local IDE.
When working with static build results, navigate to the
Then, preview your changes by opening the
Build errors are written to the