☰
Navigation :

Contributing to the Gloo Edge Documentation

Hi! So you’d like to help us out with the Gloo Edge documentation. That is awesome! Before you get started, we have a couple things to mention about contributing standards and process. We’d like to make this easy as possible, so if you have a tiny edit to make, check out the Quickstart section of the guide. Otherwise, here are the ways you can get involved:

Background

The Gloo Edge docs live in the docs/content directory of the Gloo Edge GitHub repository. The docs are written in Markdown and rendered to a static site using Hugo. The docs make use of shortcodes from Hugo and some custom shortcodes that are part of a solo-io theme stored in this repository. Shortcodes are a way to render custom HTML on a page without injecting that HTML directly into Markdown.

The docs website can be rendered locally for updates and testing by using Hugo and make. There are some software prerequisites that need to be fulfilled in order to render and view the site successfully. More information can be found in the Install prerequisite software section of the Editing Locally guide.

For minor changes and edits, it is not necessary to clone the repository and render it locally. You can simply make the changes directly on GitHub and submit a pull request (PR).

Log an issue

The simplest way to get involved with docs is by submitting an issue when you see something that needs to be changed. It could be a grammatical error, an unclear statement, or a suggestion for a new document or example. If you see something that should be amended or improved, head on over to the Gloo Edge GitHub repository and follow the steps in the Quickstart for logging an issue.

Quickstart

While it is possible to clone the entire Gloo Edge repository, make changes to the documentation, render it locally to validate, and then submit a PR; that’s a lot of work. For minor edits and small improvements, it is much simpler to edit the docs directly on GitHub and submit a pull request. Here is the quickstart process:

  1. Log an issue on the main Gloo Edge repository
  2. Fork the Gloo Edge repository to your own account
  3. Make the update and commit it
  4. Create a pull request to merge the change

Once the PR has been submitted, someone from solo.io will review the change and either approve it or ask for more information. See below for an example of creating and submitting a change.

Log an issue on the main Gloo Edge repository

In this step you will log an issue on the Gloo Edge GitHub repository so that others know you are working on a fix. You can also simply log an issue with the documentation to let others know about the problem.

Fork the Gloo Edge repository to your own account

In this step you will fork the Gloo Edge 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 Edge repository. Now you can make edits and submit a PR.

Make the update and commit it

In this step you will make the actual change to the document that has an issue. From the forked repository, select the branch you want to make changes to. The current branch being used to generate the Gloo Edge docs is main. The files that make up the docs website are in docs/content, and the directory structure follows the menu structure of the docs site.

The change has been committed to a new branch on your forked repository.

Create a pull request to merge the change

Now that the change has been committed to your fork of the Gloo Edge repository, it’s time to submit a pull request to merge the change into the official Gloo Edge repository.

Once the PR is submitted, someone from solo.io will review the change and either approve it or ask for more information.

Making big updates

While making minor edits and fixes works well on GitHub directly, more involved changes require using a proper editor and rendering the site locally. If you’d like to contribute at that level, we recommend reading through our style guide and setting up your local system properly.

Next Steps