This repository contains the source code for the http://kiali.io website.
The website is written using markdown, the Docsy theme, and generated using Hugo. It is hosted on Github and deployed using netlify.
- Requirements
- Configuring and Running
- Upgrading Hugo Version
- Documentation Versioning
- Production Deployment
- Directory Structure
- License and Code of Conduct
To run the website locally, you will need:
Generally podman is easier to setup. The dev container image includes Go (for Hugo Modules), Node/npm, and htmlproofer; Hugo extended and Dart Sass (sass-embedded) come from npm (package.json), same as Docsy’s recommended setup. Docsy is pulled as a Hugo module (go.mod); theme npm assets are merged into packages/hugoautogen/ via hugo mod npm pack.
On the host (without the container), install dependencies with npm run install:safe, then run npm run approve:hugo once to allow the hugo-extended install script. Node 24 and npm ≥11.9 match package.json engines.
Hugo has a command to run a small, self-contained web server locally, so you can test the website without having to upload/deploy it anywhere. The server supports live-reload, so changes to the content will reflect into the browser as they happen.
To run the server, you need to run the following on a terminal:
make serve
⚠️ If you are using Docker, you need to setDORPwhen starting the server; e.g:make -e DORP=docker serveOn ARM-based Macs, you'll need to run following command first:
export DOCKER_DEFAULT_PLATFORM=linux/amd64
To build and validate the site the same way CI does (Hugo production flags plus htmlproofer):
make validate-site
On the host you can also run npm test (Node maintenance scripts) and npm run build:ci after npm run install:safe.
If everything is working as expected, you should see something like this when serving (if not see Upgrading Hugo Version):
| EN
-------------------+------
Pages | 151
Paginator pages | 0
Non-page files | 1
Static files | 323
Processed images | 2
Aliases | 4
Sitemaps | 1
Cleaned | 0
Built in 1313 ms
Environment: "development"
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop
The server should be available on http://localhost:1313. Some files might not be supported for live reload. If, for some reason, you are not seeing your changes appearing you may need to restart the server.
The Hugo extended version is pinned in package.json (devDependencies.hugo-extended). Update that version and allowScripts if needed, run npm run approve:hugo, then npm run update:docsy:pack and commit package-lock.json. Netlify does not use a HUGO_VERSION environment variable; it uses the npm package.
The documentation is versioned using a branch strategy. The staging branch holds all new content. On each Kiali release staging will be captured in the current branch and the former current branch will be captured in a versioned branch. This typically happens every three weeks. Changes to
staging will be applied to all future releases. Backport or update the current, or any other versioned branch, as needed.
Deployment is done automatically when a pull request is merged, and preview deployments are also done for each PR, so you can verify that your changes will work in production before actually deploying.
The directory structure is typical for projects using the Docsy theme. A couple of notes:
- Docsy is not vendored under
themes/; it is declared ingo.modand fetched by Hugo. - The site only supports English and as such, all content is under
content/en. - The site minimizes customization but custom CSS is found in
assets/scss. - The site keeps consolidates static content under
static.- e.g. images are under
static\images
- e.g. images are under
The kiali.io website, like the other kiali-related projects are licensed under the Apache License 2.0. It also follows the Kiali Community Code of Conduct.