kpt Documentation Site#

This directory contains a Hugo web site published via Netlify to
https://kptdocs.netlify.app what is redirected to https://kpt.dev/.

When the main branch of this repo is updated a fresh build and deploy of the website is executed. Recent Netlify
builds and deployments are listed at https://app.netlify.com/sites/kptdocs.

Add content by adding Markdown files to directories in ./content.

Update layouts for each content type in ./layouts.

Configuration is set in config.toml.

Setting up a local dev instance#

To set up a local dev environment make sure you have npm installed, then run the following
from this folder:

npm install

Then run the site using make serve.

Windows note (PowerShell/CMD)#

The site pulls some dependencies via Git submodules. If npm install succeeds but the site fails to build (for example, missing theme assets), initialize submodules and try again:

git submodule update --init --recursive

Style guide for documentation#

1. Use US English in the documentation

2. Do not manually add a table of contents to the documents. Hugo and Docsy take care of this.

3. Do not use H1 (#) headers in the documents. Docsy generates an H1 header for every document
   consistent with the title of the document. Start the headings with H2 (##)

4. There are three alert types available based on the importance of the information:

   Alert type	Code	Alert color
   Note	color="primary"	Blue
   Warning	color="warning"	Yellow
   Critical	color="danger"	Red

   Make sure not to change the alert title. It should always be either Note, Warning, or Critical.

   ⧉

   {{%/* alert title="Note" color="primary" */%}}
   Important information here.
   {{%/* /alert */%}}
   

5. If you add any commands to the content inline, surround the command with backticks (` `), like ls -la

6. Do not surround IP addresses, domain names, or any other identifiers with backticks. Use italics
   (for example, *example.com*) to mark any inline IP address, domain name, file name, file location, or similar.

7. Whenever possible, define the type of code for your code blocks

   • ```shell for all shell blocks
   • ```golang for all Go blocks
   • ```yaml for all YAML blocks
   • ```yang for all YANG blocks
   • a full list of language identifiers is available here

8. Links to other kpt doc pages should be absolute:

   • Correct: [pkg]: /reference/cli/pkg/get/
   • Incorrect: [pkg]: ../../../reference/cli/pkg/get

9. Flags must appear after positional args:

   • Correct:
   ⧉

   kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace
   

   • Incorrect:
   ⧉

   kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package
   

10. The name of the tool should always appear as small caps (even at start of
    sentences) and not in block quotes:

• Correct: kpt
• Incorrect: kpt
• Incorrect: Kpt
• Incorrect: KPT

11. References to a particular KRM group, version, kind, field should appear with
    inline quotes:

• Correct: ConfigMap
• Incorrect: ConfigMap

12. Do not add any TBDs to the documentation. If something is missing, create an issue for it.

13. Do not prefix shell commands with $ in code blocks that contain only commands.
    Use $ only when a block shows both the command and its output, to distinguish
    the command from the output:

• Correct (command only):

kpt fn render my-package

• Correct (command + output):

$ kpt fn render my-package
Package "my-package":
[PASS] "ghcr.io/kptdev/krm-functions-catalog/set-labels:latest"

• Incorrect (command only with $):

$ kpt fn render my-package

License#

Licensed under the Creative Commons Attribution 4.0 International license