Add documentation

To contribute new documentation to K8sGateway, follow these steps:

• Identify the audience and intended use for the content.
• Choose the type of content you wish to contribute.
• Decide on a name, location, and other front matter for your content
• Write your contribution following the K8sGateway contribution guidelines.
• Submit your contribution as a PR to the k8sgateway/k8sgateway.io GitHub repository.
• Follow the review process until your contribution is merged.

Audience and intended use

The best documentation starts by knowing the intended users, their knowledge, and what you expect them to do with the information. Otherwise, you cannot determine the appropriate scope and depth of information to provide, its ideal structure, or the necessary supporting information. The following examples show this principle in action:

• The user needs to perform a specific task: Provide the set of steps that are required to accomplish the task.

• The user must understand a concept before they can perform a task: Before the task, tell them about the prerequisite information or provide a link to it.

• The user needs to make a decision: Provide the conceptual information necessary to know when to make the decision, the available options, and when to choose one option instead of the other.

• The user needs to understand complex feature relationships: Provide a diagram showing the relationships, rather than writing multiple pages of content that is tedious to read and understand.

After you identified your audience and the information that they need, select a suitable content type.

Content types

When you understand the audience and the intended use for the content that you want to add, you can choose the content type that best addresses the needs of the audience. The following table shows the supported content types, their intended audiences, and the goals each type strives to achieve:

File names

All documentation in the K8sGateway project is written in markdown and built by using the static site generator Hugo. In Hugo, the name of the file or folder becomes part of the link to your page. Becaues, of that, it is important to carefully choose the name for the file or folder that you want to add. If the file name consists of multiple words, separate them by hyphens. For example, to add a topic about external authentication, your file name might be ext-auth.md. All file names must be lowercase. Keep file and folder names as short as possible to ensure easy cross-linking between topics.

Front matter

Each file must start with a front matter that includes the title and weight of the file. Pick a title for your topic that has the keywords you want search engines to find. The weight configures the placement of the page in relation to other pages in the same directory, and therefore determines the order in which files are displayed in the left-hand navigation.

In the following example, the topic shows up as External authentication in the left-hand navigation.

---
title: External authentication
weight: 20
---

If you want to add a folder or “twistie” to the left-hand navigation of the docs that has multipe sub-topics, the folder must have at least one _index.md file. This file has the title of your twistie and can be used to provide general overview information about the section that you want to add. Note that you must add additional pages to your folder for the twistie to show up in the left-hand navigation. If your folder contains only an _index.md file, it shows up as a regular page. The following example shows a sample folder structure:

|-- security
|----- _index.md  // provides conceptional security information
|----- access-logging.md // guide for how to set up access logging
|----- cors.md // guide for how to set up CORS
|----- csrf.md // guide for how to set up CSRF

Hugo shortcodes

As mentioned earlier, the documentation in the K8sGateway project is built by using the static site generator Hugo. Hugo uses reusable templates, commonly referred to as shortcodes, to display, style, and render site elements, such as tables, videos, or cards and to manage the content for these elements more easily. Supported shortcodes can be found in the K8sGateway project repo as well as the Hextra Hugo theme.

Review common shortcodes that you find throughout the documentation:

reuse

You can use the reuse shortcode to reuse content in multiple places while maintaining a single source of truth. A common use case for this shortcode is a reference to the latest version, product names, or short paragraphs. The source of the reused content is stored as a markdown file in the assets/docs directory.

The following example shows the example syntax for using this shortcode:

The guide includes steps to install {{< reuse "docs/snippets/product-name.md" >}} in three ways.

The content of product-name.md is as follows:

K8sGateway

The resulting content in the web page will be rendered as:

The guide includes steps to install K8sGateway in three ways.
### reuse-image
Similar to the reuse shortcode, the reuse-image shortcode is used to display images in the documentation. Images are stored in the `assets/img` folder.

The following example shows the example syntax for using this shortcode: 

```markdown
{{< reuse-image src="img/translation.svg" >}}

To support different screen sizes, make sure to use images of type .svg only.

cards

Use the cards shortcode to display a card in the documentation that links to a specific topic within or outside the documentation. You can read more about this shortcode here.

Example card:

Shortcode syntax

{{< cards >}}
{{< card link="/quickstart" title="Get started" >}}
{{< /cards >}}

callout

A box that displays important information to the user. You can read more about this shortcode here.

Example callout:

Shortcode syntax:

{{< callout type="info" >}}
This is a sample callout of type info. 
{{< /callout >}}

Create a PR in GitHub

The K8sGateway documentation follows the standard GitHub collaboration flow for pull requests (PRs). This well-established collaboration model helps open source projects manage the following types of contributions:

• Add new files to the repository.
• Edit existing files.
• Review the added or modified files.
• Manage multiple release or development branches.

The contribution guidelines assume you can complete the following tasks:

• Fork the K8sGateway docs repository.
• Create a branch for your changes.
• Add commits to that branch.
• Open a PR to share your contribution.

Review

The documentation maintainers of the K8sGateway project will review your pull request to ensure the PR follows the documentation contribution guidelines. Once reviewed and approved by the maintainers, your PR is merged into the documentation codebase and your changes will show up on the documentation site.