Skip to content

Contributing to these docs!#

Thank you for considering contributing to our documentation. Your help is much appreciated, and we want to make the process as smooth as possible.

Prerequisites#

Before contributing, make sure you have the following installed on your system:

  • A GitHub account
  • If you want to build locally - Python (3.7 or higher)

Getting Started#

To contribute to these docs, you have two options:

Small Changes#

For small changes - if you're logged into GitHub, you can click the edit arrow at the top-right of this page. When you save, you will be given the option to open a pull request.

Larger Changes#

For larger changes, you need to set up your development environment locally. Follow these steps:

  1. Clone the repository:
git clone https://github.com/ergoplatform/ergodocs.git
  1. Install dependencies:
cd mkdocs-project
pip install -r requirements.txt
  1. Build the project:
mkdocs build
  1. Start the development server:
mkdocs serve
  1. Open the documentation in your browser:
http://127.0.0.1:8000/

Make your changes locally and submit a pull request when you're done.

Guidelines#

Writing Style#

  • Write in clear, concise, and grammatically correct English.
  • Use appropriate formatting, such as bold or italics, to emphasize key points.
  • Keep paragraphs and sections short and focused on a single topic.

Code Style#

  • Follow the code style conventions used throughout the project.
  • Include comments and explanations to make the code easy to understand.
  • Use code-blocks with syntax highlighting.

Commit Messages#

  • Write clear, concise, and meaningful commit messages.
  • Use the imperative form, e.g., "Add feature" rather than "Added feature" or "Adding feature".
  • Use sentence capitalization, i.e., capitalize the first letter of the message, but not the rest.

Notes#

The mkdocs navigation is built using mkdocs.yml. To add, remove or modify pages in the navigation, edit the nav section in the mkdocs.yml file.

Directory Structure#

The directory structure should follow this pattern:

- Parent Directory:
    - index.md
    - Sub-Directory:
        - SubDirectoryPage: subdirectorypage.md
    - ParentDirectoryPage: parentdirectorypage.md

TODOs#

To leave comments in the file itself and have them not visible on the live site, you can use the HTML comment codes:

<!-- TODO: Add information about XYZ here -->

Submitting a Pull Request#

When you're ready to submit your changes, follow these steps:

  1. Commit your changes to a new branch:
git checkout -b my-feature-branch
git add .
git commit -m "Add my awesome feature"
  1. Push your changes to your fork:
git push origin my-feature-branch
  1. Open a pull request on the original repository:

Go to the original repository on GitHub and click on the "Pull Requests" tab. Then, click on the "New Pull Request" button and select your fork and branch to create the pull request.

Please include a descriptive title and a detailed description of your changes.

Review Process#

Once your pull request is submitted, our team will review your changes. We may request additional changes or clarification before merging your pull request. Please be patient, as we want to ensure that the documentation remains high-quality and consistent.