The Service Mesh Hub docs website is generated by using Hugo along with some custom scripting. To render the site locally, you will need to have the proper software in place and a fork of the Service Mesh Hub GitHub repository cloned locally. The following guide will walk you through the basic steps of getting your local system set up properly. The guide assumes that you have a basic working knowledge of using Git and Markdown.
Install prerequisite software
The first step in the preparation process is to install the proper software on your local system. If you are developing on Linux or macOS, the installation process should be straightforward. If you are developing on a Windows system, we recommend installing the Windows Subsystem for Linux and using the Ubuntu distribution.
You're going to need some software to make all this magic happen:
Hugo - Hugo is a static site generator written in Go. You can find the installation process for Hugo on their website.
Go - Golang is a programming language created by Google. You can find the installation process for Go on their website.
Git - Git is a source control management tool. It is required to clone the Service Mesh Hub repository and submit changes. You can find the installation process for Git on their website.
Make - make is part of a standard development toolset bundled on most Linux distributions and macOS. You may need to install it using the package manager for your version of Linux. For instance, on Ubuntu you will need to run
sudo apt install build-essential.
For each software component you should install the most recent version. This document was written and tested with the following versions on Ubuntu 18.04:
- Hugo - 0.59.1
- Go - 1.14.1
- Git - 2.17.1
- Make - 4.1
Now that you have the necessary software, it's time to get the necessary files.
Get the Service Mesh Hub docs
With the correct software in place, now it is time to get the docs from the Service Mesh Hub GitHub repository. First you will fork the repository into your own GitHub account. Then you will clone the repository locally. Finally, you will use
make to render the site and then test changes.
Fork the Service Mesh Hub repository to your own account
In this step you will fork the Service Mesh Hub 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.
- On the Service Mesh Hub repository, click on the Fork button at the top of the screen
- Select your account as a destination for the fork
After a few moments the fork will complete and you will be taken to the page with your fork of the Service Mesh Hub repository. This is the repository you will clone locally.
Set up the folder structure
git clone https://github.com/your-account/service-mesh-hub.git substituting
your-account for your actual account on GitHub. You can also get the correct
.git link by clicking on the Clone or download button on your fork of the Service Mesh Hub repository.
Now move into the root of the Service Mesh Hub repository and run
TAGGED_VERSION=nonempty make download-Service Mesh Hube-changelog -B to download the latest Service Mesh Hub Enterprise changelogs, which are used to generate the changelog in the site.
You now have the repository cloned on your local filesystem, including the
docs folder that contains all of the documentation for Service Mesh Hub
Run site locally
In the previous sections you installed the necessary tools and downloaded the content to build the site. Now it's time to get that site running.
Navigate to the
docs folder from the Service Mesh Hub repo root and run
make to start up the site.
make serve-site -B
That command will download any Go dependencies and render the site using Hugo and launch a local version of the site running on port 1313. You should see output similar to this:
Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop
In a browser, navigate to http://localhost:1313 and make sure that the site loads properly. If the site loads, you are ready to start editing docs and viewing the changes in real-time.
Make changes and submit them
You've got the docs site running locally, and now you're ready to make some changes. The process for creating and submitting changes is very similar to the steps outlined in the Quickstart section of the main Contributing page.
- Log an issue on the main Service Mesh Hub repository
- Create a new branch locally for your change
- Make the update, commit it, and push to origin
- Create a pull request to merge the change to the Service Mesh Hub repository
Please remember to keep changes small and focused on a particular section of the docs. This will help to reduce collisions and make merging a simpler affair. The naming of your branch should be descriptive of the changes you are making. If you are uncertain of a change, engage with the community or tag someone on your bug report.
We want to thank you for helping make Service Mesh Hub documentation the best it can be. Editing docs isn't the most glamorous task, but for the newbie trying to learn about Service Mesh Hub they are absolutely essential.
If you haven't already had a chance, please be sure to read the style guide and take a look at the example document before you start submitting updates.