Skip to content

How to Contribute to Loki-Docs

There is two ways to contribute to the Loki-Docs repository.

  • Editing the files on Github.

  • Building the website and editing the content locally.

This guide will teach you how to build the website and edit it on your local machine.

Requirements:

You will need the following software packages:

  • Python

  • Pip

  • Mkdocs

  • github

Step 1: Installing Python and Pip

If you have and use a package manager (such as apt-get, dnf, homebrew, yum, chocolatey, etc.) to install packages on your system, then you may want to search for a "MkDocs" package and, if a recent version is available, install it with your package manager (check your system's documentation for details). That's it, you're done!

If your package manager does not have a recent "MkDocs" package, you can still use your package manager to install "Python" and "pip". Then you can use pip to install MkDocs.

Manual Installation

In order to manually install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have these already installed from the command line:

$ python --version  
Python 2.7.2  
$ pip --version  
pip 1.5.2

MkDocs supports Python versions 2.7, 3.4, 3.5, 3.6, 3.7 and pypy.

Installing Python

Install Python by downloading an installer appropriate for your system from python.org and running it.

Note: If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default).

Installing pip

If you're using a recent version of Python, the Python package manager, pip, is most likely installed by default. However, you may need to upgrade pip to the lasted version:

pip install --upgrade pip

If you need to install pip for the first time, download get-pip.py. Then run the following command to install it:

python get-pip.py

Step 2: Installing MkDocs

Install the mkdocs package using pip:

pip install mkdocs

You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay.

$ mkdocs --version  
mkdocs, version 0.15.3

For a more permanent solution, you may need to edit your PATH environment variable to include the Scripts directory of your Python installation. Recent versions of Python include a script to do this for you. Navigate to your Python installation directory (for example C:\Python34), open the Tools, then Scripts folder, and run the win_add2path.py file by double clicking on it. Alternatively, you can download the script and run it (python win_add2path.py).

Step 3: Download the loki-docs files

Now that we have mkdocs, python and pip we can download the repository to our local machine and start working on making changes.

We can download the files by typing in the terminal:

git clone [https://github.com/loki-project/loki-docs](https://github.com/loki-project/loki-docs)

You can now edit the text files locally and create pull requests when you make changes

Step 4: Making changes to loki-docs

I would suggest downloading a txt editor called sublime. In sublime click open folder and open the loki-docs directory within the software.

You’re screen should look similar to the below.

Go into the docs folder and open the desired .md file you want to edit. For the below example we are going to go into LokiNetwork.md which is in the introduction folder.

From here you can edit the file using markdown syntax. Any changes you make will automatically show up as a potential pull request.

If you have the Github gui for windows you will first need to add the local repository folder.

And now if we make any changes the Github gui will know straight away the changes we have made.

Once you’ve made all your changes click commit to master.

Step 5: Local testing

Change directories to your loki-docs local repository.

cd loki-docs

From here we can type in the terminal:

mkdocs serve

This will run Mkdocs built in development server.

When the mkdocs serve command is running any changes saved to your local repository files will be updated onto your built site.

Any issues such as links to websites or documentation that is not there or not working will show as a error when serving.

Go to http://127.0.0.1:8000/ in web browser to view the changes you’ve made prior to committing them to the Loki-docs Github.

Additional: Changing the filepaths on Loki-docs.

The file in our loki-docs folder called mkdocs.yml is where we edit the left sidebar on the Loki-docs website.

If you create any new guides you will need to save the file as a .md file within a folder that is relevant. You must also then add it to the mkdocs.yml file similar to the below.

Note: moving files within your local folders should always be reflected within the mkdocs.yml file. If you move the file within your local files but do not reflect the changes the website will not be able to find the file.