This repo houses the assets used to build the Harbor website, available at https://goharbor.io.
The website is built and developed using the Hugo static site generator.
Instructions for installing Hugo can be found here. Use the version of Hugo specified by the HUGO_VERSION environment variable in the netlify.toml configuration file, and make sure to install the "extended" version of Hugo with support for Hugo Pipes.
backport is used to backport PRs into different release branches.
The content for the Harbor blog is in content/blog, while the content for the Harbor documentation is in the docs folder.
The latest (edge) version of the documentation lives in the docs folder on the master branch, and is always viewable on https://goharbor.io/docs/edge. Documentation for specific released versions lives in its own release branch, for example release-2.1.0.
In general, all PRs should be made against the master branch to update the edge version of the docs. If you are making a change that also affects released versions, indicate which release branches to update in your PR so the website maintainers can backport your changes.
If you are making a change that is specific to a single released version of documentation, make a PR against that branch (release-X). For example, if you are fixing something specific to v2.1.0 you should make a PR against the release-2.1.0 branch only. If you are fixing something that impacts v2.1.0 docs and all future versions, you should make the PR against the master branch and so the change can also be backported to the v2.1.0 docs.
A preview of your changes is viewable through the Netlify preview linked in the PR tests. Use this to verify that your changes look good before asking the maintainers for a review. When updating the edge version make sure you add /docs/edge/ to the preview URL to see your changes.
When creating docs for a new release, please create a branch with the format release-X.Y.Z.
When you want to make these docs available through the dropdown menu, put the following into the config.toml file, above all other versions (versions are linked based on order in the config file):
[[params.versions]]
harborversion = "X.Y.Z"
helmversion = "1.3"
branchname = "release-X.Y.Z"
As last step, update the _index.md file with the new version number and correct links.
After a release, update the backport tool configuration file, .backportrc.json, with the new release branch name.
The CSS for the site is built from Sass inputs in the assets/sass directory. There is also a small amount of JavaScript logic for the site in assets/js/app.js.
The Harbor website is published automatically on the Netlify platform. Whenever changes are pushed to the master branch, the site is re-built and re-deployed, usually within about one minute.
git clone https://github.com/goharbor/website.git
cd websiteThe Markdown content for the Harbor docs is drawn from the docs folder and the release-X branches. To pull that content into your local website repo:
make prepareThis copies the docs directory and the release-X branches into this repo's content folder, separated by versions, where it can be processed by Hugo.
npm imake serveThis starts up the local Hugo server on http://localhost:1313. As you make changes, the site refreshes automatically in your browser.
To run the link checker for the Harbor website:
make check-internal-linksThis command builds the site (including drafts and future content), downloads the htmltest link checker into your local directory, and runs the checker in accordance with the configuration specified in .htmltest.yml. Only internal links are checked and all errors are piped to stdout.