CONTRIBUTING-EN.md

EMQX Documentation Contributing Guide

Thank you for your contributions to EMQX open-source project.

Table of Contents

• EMQX Documentation Contributing Guide
  • Table of Contents
  • Documentation Writing Guide
  • How to contribute
    • Request a change
    • Online editing
      • Fork
      • Commit
      • Pull request
    • Local editing
  • PR automatic check
    • Checking for broken links locally
  • How to get help

Documentation Writing Guide

To ensure consistency throughout all EMQX documentation, we kindly request all contributors reference our Documentation Writing Guide. This guideline provides detailed instructions on document structure, technical writing style, EMQX terminology, Markdown and VitePress usage, and review standards.

How to contribute

EMQX's documentation is published at https://docs.emqx.io/. You can make contributions in several different ways listed below.

Note: You will need a GitHub account to make contributions. In case you do not have one, you may follow the instructions in GitHub registration page to create one.

Request a change

Click on Edit this page or Request docs changes in the top right corner of each page of the documentation site https://docs.emqx.io/ will take you directly to the Edit or Issue pages on the GitHub site, which means you don't need to know much about Git or Markdown.

You can also directly submit an issue here from this repo's issues page.

This is similar to clicking Request doc changes on a published docs page, but if you manually file an issue you need to fill in links to the related pages.

Online editing

Fork

As you can see above, when you click on Edit this page in the top right corner of the documentation site, you will be taken to the following page on GitHub, follow the instructions, and click Fork this repository.

Commit

Click Fork this repository to jump to the document editing page and start editing your document. After completing editing, you need to enter the title and description of this submission at the bottom of the page to complete your submission.

You need to ensure that the title and description clearly describe what you are modifying.

Pull request

Click on Propose changes above and you will be redirected to the following page, click on Create pull request to submit.

After you have jumped to the following page, confirm the pull request information and click Create pull request again to complete this submission.

Local editing

Local editing requires contributors to have some Git knowledge. We recommend first-time contributors to directly use the Online editing method above to contribute documents.

1. Open the document repository https://github.com/emqx/emqx-docs for Fork.

2. Clone the forked repository into your local workspace and then go to the local directory and add the upstream repository.

   git remote add upstream https://github.com/emqx/emqx-docs.git
   

3. Checkout the earliest branch which is subject to the change. e.g. if an issue is found in EMQX 4.3, checkout release-4.3 with command git checkout --track upstream/release-4.3

4. Optional: Checkout a work-branch git checkout -b my-first-pr-branch-for-emqx-4.3

5. Edit, commit, and push the branch to your fork

   git commit -a -m 'docs(WHICH_DOC): fix xxxx in WHICH_DOC'
   git push origin my-first-pr-branch-for-emqx-4.3
   

6. Create a Pull request from your forked repository to the upstream repository.

PR automatic check

Document projects will be automatically checked according to the rules in the Documentation Writing Guide. Only the PRs that passed the checks can be merged. If you encounter a markdownlint check failure when submitting PR, the error message will indicate which line in which file is the problem, so please follow the instructions to modify and update the PR.

Checking for broken links locally

To ensure all external and internal links are valid before submitting a PR, you can use lychee, a fast link checker written in Rust.

Installation:

# macOS
brew install lychee

# Linux/Windows (using cargo)
cargo install lychee

# Or download pre-built binaries from:
# https://github.com/lycheeverse/lychee/releases

Usage:

# Check all links in English documentation
lychee --config .lychee.toml en_US/

# Check specific file or directory
lychee --config .lychee.toml en_US/getting-started/

# Check with verbose output
lychee --config .lychee.toml --verbose en_US/

# Check and show detailed results
lychee --config .lychee.toml --format detailed en_US/

Configuration:

The repository includes a .lychee.toml configuration file that:

• Excludes common false positives (localhost, example URLs, version placeholders)
• Excludes changelog directories
• Sets appropriate timeouts and retry settings
• Throttles requests to avoid 429 (Too Many Requests) errors:
  • Max 5 concurrent requests
  • Max 10 requests per second
  • 5 second wait time between retries
• Caches results to speed up subsequent runs

Common issues:

• 429 Too Many Requests: The tool is already configured with throttling, but if you still encounter rate limiting, try:
  • Checking smaller directories at a time
  • Increasing the delay between requests in .lychee.toml (reduce max_requests_per_second)
• 403 Forbidden errors: Some sites block automated link checkers. These may need manual verification.
• Timeout errors: Increase timeout in .lychee.toml if you have a slow connection.
• Fragment checking: Disabled by default since VitePress generates anchors during build time.

Note: Link checking is also performed automatically by CI on pull requests to release branches.

How to get help

If you encounter any problems when contributing to the documentation, you can contact us for getting help in the following methods.

• Slack: https://slack-invite.emqx.io/

• Submit the GitHub Issue directly: https://github.com/emqx/emqx-docs/issues/new.