Working with GitHub

We’re excited that you’re interested in contributing to improve and expand our docs! Please take a few moments to get familiar with our procedures before you get started.

To work on Istio documentation, you need to:

  1. Create a GitHub account.

  2. Sign the Contributor License Agreement.

The documentation is published under the Apache 2.0 license.

How to contribute

There are two ways you can contribute to the Istio documentation:

  • If you want to edit an existing page, you can open up the page in your browser and select the Edit This Page on GitHub option from the gear menu at the top right of each page. This takes you to GitHub to edit and submit the changes.

  • If you want to work on the site in general, you must create a fork of the repository. Click the button below to visit the GitHub repository. Then, you must click the Fork button in the upper-right corner of the screen to create a copy of our repository in your GitHub account. Create a clone of your fork and make any changes you want. When you are ready to send those changes to us, push the changes to your fork, go to the index page for your fork, and click New Pull Request to let us know about it.

Browse this site’s source code

Once your changes are merged, they show up immediately on preliminary.istio.io. However, the changes only show up on istio.io when the next time we produce a new release, which happens around once a month.

Previewing your work

When you submit a pull request, your PR page on GitHub shows a link to a staging site built automatically for your PR. This is useful for you to see what the final page looks like to end-users. Folks reviewing your pull request also use this staging site to make sure everything looks good.

If you created a fork of the repository, you can preview your changes locally. See this README for instructions.

See also

Explains the dos and donts of writing Istio documentation.

Explains the mechanics of creating new documentation pages.