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.

  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:

    • Build the linter with npm run md:lint-fix.

    This task should result without errors.

  8. Commit Your Changes.

  9. Push to Your Fork.

  10. Open a Pull Request (PR).

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. 🎉