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.
You will need the following software packages:
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.
$ 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.
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).
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
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.
From here we can type in the terminal:
This will run Mkdocs built in development server.
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.