Editing Locally

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:

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:

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.

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

Run 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.

Now move into the root of the Gloo repository and run TAGGED_VERSION=nonempty make download-glooe-changelog -B to download the latest Gloo Enterprise changelogs, which are used to generate the changelog in the site.

You now have the repository cloned on your local filesystem, including the docs folder that contains all of the documentation for Gloo, as well as the latest Gloo Enterprise changelogs saved into ../solo-projects/changelog.


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.

make serve-site -B

That command will download any Go dependencies and render the site using Hugo and launch a local version of the site running on port 1313. 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.

  1. Log an issue on the main Gloo repository
  2. Create a new branch locally for your change
  3. Make the update, commit it, and push to origin
  4. 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.


Next Steps

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.