Handbook
This is documentation about the handbook itself 
Gitbook
We use gitbook to build the handbook.
It's a common way to present handbooks online, see the handbooks from Enspiral and Loomio for other examples.
We don't use the hosted version at gitbook.com as it has a limit of 5 editors, and it seems nice if everybody that edits it uses the same approach.
How to contribute
The content is stored at gitlab.com/kanthaus/handbook.
First, make sure you have access rights:
- create an account at gitlab.com if you don't already have one
- ask someone in #kanthaus slack channel to give you the right permissions
Next, understand the two approaches you can take:
- edit directly in the GitLab interface
- clone the git repository to your computer, make changes, then push them back
Editing in GitLab interface
You can click the EDIT THIS PAGE button at the top of any page, and it will take you to the appropriate page to edit on GitLab.
The content is written in markdown, if you are not familiar with markdown you can learn more about it at markdownguide.org.
Once you have made your changes you can optionally edit the comit message, then press Commit changes.
After a few minutes the changes will be live on the website!
Editing on your local computer
For this you will (probably) need to become familiar with:
- the command line
- git
- editing markdown files
- gitbook
- nodejs and yarn
- ssh keys (optionally)
Firstly, clone the repository:
git clone https://gitlab.com/kanthaus/handbook.git
(note if you want to use ssh keys you'll need to use git@gitlab.com:kanthaus/handbook.git instead).
You'll then have a directory called handbook wherever you ran the command. We need to enter the directory and install the dependencies:
cd handbook
yarn
Now you're ready to run it locally on your computer:
yarn serve
This will build the book and serve it up at localhost:4000, you can visit that in your favourite web browser.
Now you can edit the content, I recommend using visual studio code for editing.
Any changes you make will trigger your browser to reload the new content!
Once you're happy with your changes, we need to commit them to the repository, and push them back to GitLab:
# tip: see which files you've added/changed
git status
# add all changes in your local directory
git add .
# ... OR add changed files individually
git add handbook.md
# tip: check status again to see which files you're about to commit
git status
# tip: see the content you're about to commit
git diff --staged
# note: make sure your commit message is informative!
git commit -m "Clarified the handbook page"
# push the changes back to GitLab
git push
After a few minutes the changes will be live on the website!
When you next come to edit, you should make sure you have the latest changes from other people too:
# fetch changes from the remote GitLab server
git pull
If it tells you there are conflicts it probably means someone else has edited that page and git does not know how to combine your changes (it can combine unrelated changes quite easily).
You can try and teach yourself how it works (search for "resolve git conflict" or similar) but also you can just ask someone to help you :) Git can be quite confusing.
Deployment
We use GitLab CI to build the gitbook, then rsync to deploy it to yuca.yunity.org where it is served at handbook.kanthaus.online.
You can check the status or progress by viewing the pipelines.
Emojis
You can use emojis from this emoji cheat sheet 
