Build and Deploy the Istio Documentation site locally

Istio is the most popular service mesh in the industry today. It is backed by a comprehensive documentation hosted at https://istio.io/latest/docs/

Like any open source project, Istio's documentation relies heavily on the contributions from the community. If you are passionate about documentation and would like to make a contribution, the first step is to set up the documentation site locally. In this article, we will learn the basic steps to achieve this.

Prerequisites

Local Setup

Fork the repository

Create a fork of the istio/istio.io repository

Clone the fork

💡

Use the url of your forked repo

git clone https://github.com/adityasamant25/istio.io

Create a branch

💡

'issue-10' has been used as an example for the branch name

// Navigate to the project directory
cd istio.io
git checkout -b issue-10

Deploy the website locally

Istio provides a Docker image with all the tools needed, including Hugo which is the site generator. To build and publish the website locally within the docker container, execute the command below:

make serve

💡

In case you receive an error stating "Failed to read Git log: fatal: detected dubious ownership in repository at '/work'", execute the below command locally and then run the make serve command again.

git config --global --add safe.directory /work

Once the website builds successfully, you should see the following message:

Built in 18037 ms
Environment: "development"
Serving pages from disk
Web Server is available at http://localhost:1313/latest/ (bind address 0.0.0.0)

Access the URL http://localhost:1313/latest/ from within a browser. The Istio documentation is now available to you locally.

Contribute changes

The documentation for the English language is available at the following path:

/content/en/docs

Navigate to the .md file you need to edit. Make the appropriate changes and save the file. Saving the changes automatically triggers a redeployment of the site. The browser refreshes automatically and this enables you to immediately validate your changes locally.

Once you are satisfied with your changes, perform the following steps:

Commit the changes to your local branch

  git add <file paths>
  git commit -m "Fixed issue 10"

Push the changes to a branch on your fork
```
  git push origin issue-10
```
Raise a pull request from your branch to the istio.io master branch

After you raise a pull request, wait for a maintainer to review the changes. In case of any review comments, incorporate the changes and push a new commit.

Conclusion

Hope this article helps in getting you started on your journey to contribute to Istio documentation. In case of any issues, please post a reply and I will try to assist.

Aditya Samant