Skip to content

📄 Contributing to the Documentation#

Good documentation is crucial for our project's success!
We truly appreciate any contributions, whether it's fixing a typo, clarifying a section, adding more examples, or even extending existing topics. This guide will walk you through the process of contributing.

The entire documentation lives in the docs/ folder of this repository.

  1. Follow the Workflow:

  2. Serve the Documentation Locally: Start the local development server.
    This task needs to be run from the project root (where the mkdocs.yml file is):

    mkdocs serve

    This will usually launch a local server, at http://127.0.0.1:8000. The server will automatically reload in your browser as you make and save changes to the documentation files.
    To stop the server, press Ctrl + C in the terminal.

    Note

    This command previews the "current" state of your files. It will not show the version selector dropdown.

  3. Edit Markdown Files: All documentation content is written in Markdown (.md files). You can find them within the docs/ folder.

  4. Add New Pages:

    • Create a new .md file in the most appropriate directory within docs/.

    Important

    You'll need to add the new page to the navigation (nav) section of the mkdocs.yml file for it to appear in the sidebar. Follow the existing structure.

  5. Add Images:

    • Place any image files into the docs/images/ directory.
    • Reference them in your Markdown using the syntax: ![Alt text for accessibility](images/your-image-name.png)

  6. Preview Changes: As you save your .md files, the local server running at http://127.0.0.1:8000 will automatically refresh, allowing you to see your changes instantly.

  7. Format and Lint Your Changes:

    To keep the documentation clean and consistent, run the linter before committing.
    This checks for broken links, formatting issues, and common Markdown errors.

    npm run md:lint-fix

This task should result without errors.

  1. Commit Your Changes.

  2. Push to Your Fork.

  3. Open a Pull Request (PR).

How Versioning Works#

Our documentation uses mike to manage multiple versions of the documentation:

  • The main version: Every time a Pull Request is merged into the main branch, the documentation at /main/ is updated.
    This represents the "development" or "upcoming" version.

  • The latest version: This points to the most recent official release.

  • Tagged versions: When we create a new GitHub Release, a permanent, numbered version (e.g., v1.2.0) is created and archived in the version selector.

Documentation Style and Quality#

To maintain consistency and quality:

  • Clarity and Conciseness: Use straightforward, clear, and concise language.
  • Examples: Include images and code examples whenever they help clarify a point.

Thank you for taking the time to help us improve our documentation! Your contributions make a real difference. 🎉