Contributing to this book


First way to contribute

You can easily suggest edits by clicking on the button at the top right

suggest an edit centered


Second way to contribute

This book is written using mdBook. To contribute to this book, you will need:

  1. mdBook
  2. git
  3. GitHub account
  4. (Optional) VSCodium

VSCodium or VSCode is highly recommended to use. Although it is optional, I will assume you are using it.

Below I describe the setup steps needed to run and contribute to this book. But before that, go and install VSCodium and Git.

Forking book repository

Contributing to this book follows the standart "Pull Request" workflow. That basically means that you will have your own copy of the book, and you will ask us to pull your changes into the main repository.

Here is the overview of steps needed for contributing:

  1. Copy ("fork") the main repository
  2. Download your copy of repo
  3. Add your changes to your copy
  4. Upload your changes
  5. Open the Pull Request to merge your changes into main repository

Welp, let's get started. I hope you already have a GitHub account.

Forking

  1. Go to the main repo

  2. Press the fork button

    centered

  3. Create the fork

    centered

  4. You're awesome

Downloading your repo

  1. Open the folder you want to download into in VSCodium. In my case, it will be Desktop.

    centered

  2. Open Poweshell Terminal session

  3. Copy the link to your repo.

    centered

  4. Run the following command in your Powershell Terminal with your link instead of LINK.

    git clone LINK
    
  5. You're awesome.

Running local copy

  1. Download latest mdbook from Github Releases.
  2. Drop mdbook.exe in the root folder of your copy.
  3. Run run.bat. In case it doesn't open by itself, open localhost:3000 in your browser.
  4. Done. You're awesome.

Uploading your changes

  1. Set your git up. Here's a great guide

  2. Add your changes using VSCodium git tab. Open git tab, hover over "Changes" line and press "+".

    centered

  3. Add a nice message and press "✔" to commit your changes

    centered

  4. You should now be able to publish your changes

    centered

Creating Pull Request

  1. In main book repository, open "Pull Requests" tab and press "New pull request"

    centered

  2. Press "compare across forks". Choose your repository and press "Create pull request".

  3. You're awesome. Probably. Now ping Igigog#6387 in Discord to get your pull request reviewed.

  4. Done. Your changes are added to the main book.


P.S

If you will be using VSCodium or VSCode, it is recommended to install markdown extensions to make life easier or to avoid messing up the book structure.

For example such as:

  • Markdown Link Updater - Updates Markdown links automatically, when files in the workspace are moved or renamed.
  • markdownlint - This is a rule library for encouraging standards and consistency for Markdown files.