Editing Locally

The Gloo Gateway 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 Gateway 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 Gateway 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.81.0
• Go - 1.20.3
• 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 Gateway docs

With the correct software in place, now it is time to get the docs from the Gloo Gateway 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 Gateway repository to your own account

In this step you will fork the Gloo Gateway 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 Gateway 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 Gateway 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 Gateway repository.

You now have the repository cloned on your local filesystem, including the docs folder that contains all of the documentation for Gloo Gateway.

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 Gateway repo root and run make to start up the site.

cd docs
export GITHUB_TOKEN=foo
SKIP_CHANGELOG_GENERATION=true SKIP_SECURITY_SCAN=true SKIP_ENTERPRISE_DOCS_GENERATION=true HUGO_PARAMS_noSecurityScan=true make serve-site -B

Those commands download any Go dependencies and render the site using Hugo.

• the SKIP_CHANGELOG_GENERATION part tells the program to avoid pulling changelog documentation from git
• the SKIP_SECURITY_SCAN skips the Trivy security scan
• the SKIP_ENTERPRISE_DOCS_GENERATION skips fetching some documentation from a private Solo.io GitHub repository
• the HUGO_PARAMS_noSecurityScan=true variable tells Hugo not to render security scan reports, which requires a corporate Solo.io GH account

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.

1. Log an issue on the main Gloo Gateway 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 Gateway 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 Gateway documentation the best it can be. Editing docs isn’t the most glamorous task, but for the newbie trying to learn about Gloo Gateway 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.