Style Guide

The documentation for Gloo is meant to be conversational and engaging. It should also be easy to read and inviting for the newcomer. In an attempt to maintain a consistent voice and style throughout the docs, please use the following conventions when approaching a new document or revising an existing one.

Style guide


Document naming and structure

The docs use Hugo to generate the static website, which makes the structure and naming of the directories holding the content important. The structure of the current docs can be found on the Gloo GitHub repository. Here is a representation of content directory as of this writing.

# Menu item in the navigation bar
├───api
├───changelog
├───cli
├───contributing
├───dev
├───getting_started
├───gloo_integrations
├───gloo_routing
│   ├───hello_world # Nested menu item
│   ├───tls
│   ├───validation
│   ├───virtual_services
│   └───_index.md # Base page of the gloo_routing menu item
├───img
├───installation
├───introduction
├───observability
├───security
├───static
├───upgrading
└───_index.md # Base page of the website

Each directory appears as a menu item on the navigation bar. The page that loads when the menu item is clicked will be the _index.md file in that directory. Additional files in that directory will appear based on the value assigned to the title field in the header of the document. The order of the files is controlled by the value assigned to the weight field in the header of the document.

To create a new menu item, simply create a directory at the root of the content directory or in the sub-directory where you want the menu item to appear. Then add an _index.md file to that directory and populate it with content. The weight value in the _index.md file determines the order in which the menu item will appear among the parent items. For instance, the _index.md file found in the introduction directory has a weight value of 10. This places the Introduction menu item at the top of the navigation bar. The weight value for additional files in a directory determine their order within the expanded menu item in the navigation pane. More information can be found on the Hugo website if you really want to do a deep dive.

Next Steps

Now that you have a firm grasp of how the docs should be written, you can start writing your first doc or get set up on your local workstation.