Istio Documentation - Local Build and Deploy
If you're interested in contributing to Istio's documentation, then learn how to get started by deploying the site locally.
Photo by Super Snapper on Unsplash
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
git clone https://github.com/adityasamant25/istio.io
Create a branch
// 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
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.