The Gloo docs website is generated by using Hugo along with some custom scripting. To render the site locally, you will need to have the proper software in place and a fork of the Gloo GitHub repository cloned locally. The following guide will walk you through the basic steps of getting your local system set up properly. The guide assumes that you have a basic working knowledge of using Git and Markdown.
Install prerequisite software
The first step in the preparation process is to install the proper software on your local system. If you are developing on Linux or macOS, the installation process should be straightforward. If you are developing on a Windows system, we recommend installing the Windows Subsystem for Linux and using the Ubuntu distribution.
You’re going to need some software to make all this magic happen:
Hugo - Hugo is a static site generator written in Go. Unlike the other programs listed here, You need a specific version of Hugo for this to work, which is noted in the docs makefile as
HUGO_VERSION. You can find the installation process for Hugo on their website. Refer to the tarball installation section for instructions on downloading specific versions.
Go - Golang is a programming language created by Google. You can find the installation process for Go on their website.
Git - Git is a source control management tool. It is required to clone the Gloo repository and submit changes. You can find the installation process for Git on their website.
Make - make is part of a standard development toolset bundled on most Linux distributions and macOS. You may need to install it using the package manager for your version of Linux. For instance, on Ubuntu you will need to run
sudo apt install build-essential.
For each software component you should install the most recent version. This document was written and tested with the following versions on Ubuntu 18.04:
- Hugo - 0.59.1
- Go - 1.13.5
- Git - 2.17.1
- Make - 4.1
Now that you have the necessary software, it’s time to get the necessary files.
Get the Gloo docs
With the correct software in place, now it is time to get the docs from the Gloo GitHub repository. First you will fork the repository into your own GitHub account. Then you will clone the repository locally. Finally, you will use
make to render the site and then test changes.
Fork the Gloo repository to your own account
In this step you will fork the Gloo repository into your own account. This step assumes that you already have a GitHub account. More information on forking a repository can be found on GitHub’s website.
- On the Gloo repository, click on the Fork button at the top of the screen
- Select your account as a destination for the fork
After a few moments the fork will complete and you will be taken to the page with your fork of the Gloo repository. This is the repository you will clone locally.
Set up the folder structure
git clone https://github.com/your-account/gloo.git substituting
your-account for your actual account on GitHub. You can also get the correct
.git link by clicking on the Clone or download button on your fork of the Gloo repository.
You now have the repository cloned on your local filesystem, including the
docs folder that contains all of the documentation for Gloo.
Run site locally
In the previous sections you installed the necessary tools and downloaded the content to build the site. Now it’s time to get that site running.
Navigate to the
docs folder from the Gloo repo root and run
make to start up the site.
SKIP_CHANGELOG_GENERATION=true make serve-site -b
That command will download any Go dependencies and render the site using Hugo, then launch a local version of the site running on port 1313. The
SKIP_CHANGELOG_GENERATION part tells the program to avoid pulling changelog documentation from git. Once the command completes, you should see output similar to this:
Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop
In a browser, navigate to http://localhost:1313 and make sure that the site loads properly. If the site loads, you are ready to start editing docs and viewing the changes in real-time.
Make changes and submit them
You’ve got the docs site running locally, and now you’re ready to make some changes. The process for creating and submitting changes is very similar to the steps outlined in the Quickstart section of the main Contributing page.
- Log an issue on the main Gloo repository
- Create a new branch locally for your change
- Make the update, commit it, and push to origin
- Create a pull request to merge the change to the Gloo repository
Please remember to keep changes small and focused on a particular section of the docs. This will help to reduce collisions and make merging a simpler affair. The naming of your branch should be descriptive of the changes you are making. If you are uncertain of a change, engage with the community or tag someone on your bug report.
We want to thank you for helping make Gloo documentation the best it can be. Editing docs isn’t the most glamorous task, but for the newbie trying to learn about Gloo they are absolutely essential.
If you haven’t already had a chance, please be sure to read the style guide and take a look at the example document before you start submitting updates.