In order to contribute to the Documentation efforts, you can edit pages directly on Github. But if you want a more powerful setup for a better work experience, you can choose to set up a local copy of the files, install our build engine Hugo, and build and serve the site locally.
This is an advanced way of editing the Documentation, it should only be used by people with the necessary technical skills and who want to work on this Documentation extensively.
We need to be running the following packages:
Git (for source-control)
Asciidoctor (to handle Asciidoc mark-up)
Hugo (static-site engine)
The following instructions are specific to Ubuntu 64-bit, but should be easy to adapt to other Linuxes and MacOS. A Windows installation is also possible. See the links at the bottom of this article for specific instructions for other environments.
sudo apt-get update
sudo apt-get install git
sudo dpkg -i hugo_0.36_Linux-64bit.deb
Check Hugo is operational with
hugo version
Go to some appropriate directory, and use this command to create the SuiteDocs subtree and download everything:
cd SuiteDocs
bundle install
That should pick up the local Gemfile asking for the "asciidoctor" package and install it. Check with:
asciidoctor --version
You’re ready to go! To build the site you can simply type
hugo
But you won’t be using that very often because it’s enough to launch the local web server, and any outstanding changes will get rebuilt:
hugo server --bind=0.0.0.0 --baseUrl=http://10.0.0.200 --navigateToChanged
Change that 10.0.0.200 into whatever is your local IP address.
This will be the URL you put in your browser to navigate the local website.
While doing your work on content, we recommend keeping a second terminal window always running the server, so you can check any error messages, and see the server picking up your edits automatically and redeploying.
Apart from the advantages of collaborating on content via GitHub, this local setup lets you use the full
power of Linux over your content, to grep it, bash it, php it… mass operations are quick and easy.
The fast, automatic redeployments, complete with automatic browser navigation to changed content, are extremely convenient while editing content.
Finally, the entire site is up for editing - not just textual content but also visual aspects, features, etc. Your contribution can be a new site feature coded in Golang.
Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.