:toc: macro
:toc-title:

= Kiali.io

https://app.netlify.com/sites/kiali/deploys[image:https://api.netlify.com/api/v1/badges/05b3eed1-6ea2-41a1-8b64-c76bda241be6/deploy-status[title="Netlify Status"]]

toc::[]

This repository contains the source code for the http://kiali.io[http://kiali.io] website.

The website is written using http://asciidoctor.org[AsciiDoc], generated using https://gohugo.io[Hugo], hosted on Github and deployed using netlify.


== Requirements ==
To run the website locally, you will need:

* https://docker.io[Docker] or https://podman.io[Podman]
* https://www.gnu.org/software/make/[GNU Make]

Generally `podman` is easier to setup, but less used due to being newer.


== Configuring and Running ==
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:

[source,shell]
----
make serve
----

[NOTE]
====
If you are using podman, you need to set `CONTAINER_RUNTIME` when starting the server, as such:
====

[source,shell]
----
CONTAINER_RUNTIME=podman make serve
----

If everything is working as expected, you should see something like this:

[source,]
----
                   |  EN
+------------------+------+
  Pages            | 1353
  Paginator pages  |    0
  Non-page files   |    0
  Static files     |  119
  Processed images |    0
  Aliases          |  155
  Sitemaps         |    1
  Cleaned          |    0

Total in 15304 ms
Watching for changes in /site/{content,data,layouts,static,themes}
Watching for config changes in /site/config.toml
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[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.

=== Faster generation ===

The website generation includes every past releases of the documentation, which might be slow and unnecessary. Instead of generating everything, you can speed up the process if you're only interested in latest or staging version. To do so, run the following:

[source,shell]
----
make serve-latest
# or, with podman:
CONTAINER_RUNTIME=podman make serve-latest
----

It will move the archived documentation to a temporary location before starting the server, and put it back once the server is closed. Just double-check it's back to its original place before committing (ie. there's no undesired deleted/moved content in your git status).

== Documentation Versioning ==

The documentation is versioned, and all new changes should go to `content/documentation/staging`. The release script runs every 3 weeks usually and generates a `content/documentation/vX.X` with the contents of staging, as well as creating a symbolic link on `content/documentation/latest`.

The versioning/release script can be found on `scripts/build-archive.sh`.

== Production Deployment ==

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.

== Directory Structure ==

* archetypes :: Content definitions, tag, categories and so on
* content :: Content for the website (pages and articles)
** contribute :: Contribution how-to
** documentation :: Documentation for Kiali
*** staging :: The documentation for the next released versions, changes should go here
*** latest :: A symbolic link to the latest generated version, replaced on release
*** vX.X :: Documentation for older versions, those are usually generated by the release scripts
** news :: News about the project
* data :: Website data, such as localization configuration
* layouts :: Page layout templates
* public :: Content for website automatically generated by Hugo, it is not included in the repository
* scripts :: Scripts for generating swagger documentation and versioning
* static :: Any static files that need to be added to the website (images, css and js)
* themes :: The website theme


== License and Code of Conduct ==

The kiali.io website, like the other kiali-related projects are licensed under the https://www.apache.org/licenses/LICENSE-2.0[Apache License 2.0]. It also follows the https://github.com/kiali/kiali/blob/master/CODE_OF_CONDUCT.md[Kiali Community Code of Conduct].
