https://github.com/minio/kes-docs
Documentation for the MinIO Key Encryption Service (KES)
https://github.com/minio/kes-docs
documentation
Last synced: 9 months ago
JSON representation
Documentation for the MinIO Key Encryption Service (KES)
- Host: GitHub
- URL: https://github.com/minio/kes-docs
- Owner: minio
- License: cc-by-4.0
- Created: 2022-09-16T21:13:14.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-08-12T17:51:51.000Z (11 months ago)
- Last Synced: 2025-10-07T03:40:56.751Z (9 months ago)
- Topics: documentation
- Language: Shell
- Homepage: https://github.com/minio/kes
- Size: 8.04 MB
- Stars: 3
- Watchers: 5
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MinIO's Key Encryption Service (KES) Documentation
The KES docs use [Hugo](https://www.gohogo.io) to generate static HTML pages.
- [MinIO's Key Encryption Service (KES) Documentation](#minios-key-encryption-service-kes-documentation)
- [Prerequisites](#prerequisites)
- [Initial Setup](#initial-setup)
- [Update Theme from Upstream Repository](#update-theme-from-upstream-repository)
- [Build Preview](#build-preview)
- [Build for production](#build-for-production)
- [Style](#style)
- [Markup](#markup)
- [Style Guides](#style-guides)
- [Spelling](#spelling)
- [Code Blocks](#code-blocks)
- [Shortcodes](#shortcodes)
- [Internal linking](#internal-linking)
- [Components (Tabs, Admonitions, Cards, etc.)](#components-tabs-admonitions-cards-etc)
- [Frontmatter](#frontmatter)
- [Custom Frontmatter params](#custom-frontmatter-params)
## Prerequisites
- Any [operating system that Hugo supports](https://gohugo.io/installation/)
- [nodejs](https://nodejs.org/en/download/package-manager/) 16.9.x or later
- [Node Package Manager](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed (8.5.0 or later)
- [Hugo installed](https://gohugo.io/installation/) (0.110.0 or later)
## Initial Setup
1. Clone this repository
2. cd to the directory (`cd kes-docs`)
3. Initialize the theme directory submodule
```
git submodule update --init --recursive
```
4. `cd themes/kes-docs-theme`
5. `npm install`
6. `npm run build`
7. `cd ../../`
## Update Theme from Upstream Repository
The theme we use in the docs is hosted and maintained in a separate, private repository.
We use a the git submodule functionality to include it here.
After updating the theme, re-install node packages and then re-build the theme assets.
To pull new updates to the theme from the upstream repository, run the following:
```
git submodule update --recursive --remote
cd themes/kes-docs-theme
npm install
npm run build
```
**Note:** You must have access to the remote theme repository, which is a private MinIO repository.
## Build Preview
You can launch a live preview of the site as you work.
1. From your terminal in the repository folder, run
```shell
hugo server
```
2. In your browser, go to `localhost:1313`
## Build for production
To build the site for production or to upload to the staging server:
1. Run
```shell
hugo
```
2. Contents go to the `/public` directory in the repo folder.
## Style
### Markup
We write in [Goldmark Markdown](https://github.com/yuin/goldmark/) as extended by [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/) and our own [shortcodes](#shortcodes).
Goldmark is fully [Commonmark](https://commonmark.org/help/) compliant.
### Style Guides
MinIO uses an internal style guide.
Allow maintainers to modify your branch when you submit your PR so that we can adjust for internal style consistencies.
Otherwise, follow these resources in order of preference:
1. [MongoDB Style Guide](https://www.mongodb.com/docs/meta/style-guide/quickstart/)
2. [ASD-STE-100 Simplified Technical English](https://asd-ste100.org/STE_downloads.html#features16-x)
3. [Google Developer Style Guide](https://developers.google.com/style/)
### Spelling
We write in American English, using [Merriam Webster's online dictionary](https://www.merriam-webster.com/) as the standard spelling reference.
### Code Blocks
To add a copy button to a code block, add `{.copy}` after the language format.
For example
```md
```yaml {.copy}
tls:
key: ./server.key # Path to the TLS private key
cert: ./server.cert # Path to the TLS certificate
password: "" # An optional password to decrypt the TLS private key
```
The code block *must* have a valid language type for the copy function to work.
## Shortcodes
Hugo uses shortcodes to extend what is normally available with Markdown.
### Internal linking
To link to another page within the docs, use the following format.
```Markdown
[link text]({{< relref "path/to/page/#heading" >}})
```
### Components (Tabs, Admonitions, Cards, etc.)
Refer to `themes/kes-docs-theme/README.md`.
## Frontmatter
We use YAML-formatted [front matter](https://gohugo.io/content-management/front-matter/).
Pages should have at least the following front matter tokens:
```yaml
---
title:
date: YYYY-MM-DD ## date of file creation
lastmod: :git ## this is retrieved from git and should not be modified
draft: false ## set to true if the document is not yet ready for publication
tableOfContents: true ## creates a right-side page navigation TOC, set to `false` if not needed
---
```
### Custom Frontmatter params
Refer to `themes/kes-docs-theme/README.md`.