Skip to content

README.md

Latest commit

 

History

History
133 lines (89 loc) · 4.43 KB

README.md

File metadata and controls

133 lines (89 loc) · 4.43 KB
Raw

kpt Documentation Site

Netlify Status

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
  1. References to a particular KRM group, version, kind, field should appear with inline quotes:
  • Correct: ConfigMap
  • Incorrect: ConfigMap

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

  2. 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