Repository files navigation

This repository contains the source content and code forKong's documentation website. It's built usingJekyll and deployed withNetlify.

Here are some things to know before you get started:

• We're beginner-friendly. Whether you're a Technical Writer learning about docs-as-code or an engineer practicing your documentation skills, we welcome your involvement. If you'd like to contribute and don't have something in mind already, head on over toIssues. We've addedgood first issue labels on beginner-friendly issues.

• We need more help in some areas. We'd especially love some help withplugin documentation.

• Some of our docs are generated.

  • Admin API
  • CLI reference
  • OSS upgrade guide
  • PDK reference

All pull requests for these docs should be opened in theKong/kong repository. Fork the repository and submit PRs from your fork.

ForGateway Enterprise configuration reference, open an issue on this repo and we'll update the docs.

• Community is a priority for us. Before submitting an issue or pull request, make sure to review ourContributing Guide and ourdocumentation templates.

• We are currently accepting plugin submissions to our plugin hub from trusted technical partners, on a limited basis. For more information, see theKong Partners page.

For anything other than minor changes,clone the repository onto your local machine and build locally. Once you've installed all of the tools required, you can use ourMakefile to build the docs:

# Install dependenciesmake install# Make sure to update submodulesgit submodule update --init --recursive# Build the site and watch for changesmake run

If you have contributed a plugin, you can add a Kong badge to your plugin README.

Use the following, where you replacetest with your plugin name andlink-to-docs with a link to the Kong docs for your plugin.

[![](https://img.shields.io/badge/Kong-test-blue.svg?colorA=042943&colorB=00C4BB&style=flat&longCache=true&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAIAAAAC64paAAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAAOwgAADsIBFShKgAAAABl0RVh0U29mdHdhcmUAcGFpbnQubmV0IDQuMC4xOdTWsmQAAAIcSURBVDhPY2DRdCYb0Vgzh46btlcCmiAEEdDMb+w9a+Xmr99/FHdM49R1R5PFp5nPyHvfifP/weDvv39LNu4SMfdHVoBPs2VY9q4jpx8+ewnRDwRHz13h1veAK8CpmdfQq6xrRt2EeS7xxc9evYVovvf4mbhlIFwNTs1JlV1///4Fajh96UZIbt2nL1+B7B8/fznGFsDVYNcsYRX04jXUtn///m3ae7SgZcrnr9/aZixBDjYsmnn0Pe2j85++fAPRDAR///6btGitWXAGu7Yrskp0zaLmAWt2HLxy+35UUcvHzyCnQsCv37/zWiaxabkgK0ZoFrMIMA3OOH/t9j+w6j3HzmbW9wE9CeaBwJdv30PyGuDqgQiqWdDU9/TlG99//IQqBHt1wbodjZMX/PnzByr0///rdx+sI3JQNAMT4ML1O6HySOD3nz+FbVOBUsAUAhUCx5aqawxCc2HbFKA9UEmwHqATgOjdx092UXmCJr57j5+DyoHBqUs3RC0CoJqRXfv795/sxol+GVVA5JJQzK3vCVQgZx92+eY9qApI5O07BtUMFQODGcs3RRY1v3zzHug9IJq4cA3QU0A1+r7JT168hir6/x/IZtVyQdF85spNYGYAOunh0xcQEWAM5TRNBKoBIo/ksi9fv0PEgdEJFAFpvnbnARBduH4Hnm+BKQkiCETAMGfTBkWviJn/3mNnIYKp1d1QzWQiTWcA1wsS5+E9q+MAAAAASUVORK5CYII=)](link-to-docs)

Here's how the badge looks:

SeeIssue #908 for more information. Note that we're not currently hosting assets for badges.

This section is for Kong source code maintainers. You don't need to do anything here if you're contributing to this repo!

The PDK docs, Admin API docs,cli.md andconfiguration.md for each release are generated from the Kong source code.

To generate them, go to theKong/kong repo and run:

scripts/autodoc<docs-folder><kong-version>

For example:

cd /path/to/kongscripts/autodoc ../docs.konghq.com 2.4.x

This example assumes that theKong/docs.konghq.com repo is cloned into thesame directory as theKong/kong repo, and that you want to generate the docsfor version2.4.x. Adjust the paths and version as needed.

After everything is generated, review, open a branch with the changes, send apull request, and review the changes.

You usually want to open a PR against arelease/* branch. For example, in theexample above, the branch wasrelease/2.4.

cd docs.konghq.comgit fetch --allgit checkout release/2.4git checkout -b release/2.4-autodocosgit add -A.git commit -m"docs(2.4.x) add autodocs"git push

Then open a pull request againstrelease/2.4.

Tests for this site are written usingfetch,cheerio andjest

To run the tests, you must first build the site by runningmake build before runningmake smoke.

Many of the tests are smoke tests to check for issues that occurred while adding caching to the site, such as ensuring that the side navigation isn't cached.

To add your own tests, look in thetests directory and usehome.test.js as a sample. You specify which URL to visit and then a CSS selector to search for, before asserting that the contents match what you expect.

test("has the 'Welcome to Kong' header",async()=>{const$=awaitfetchPage("/")expect($("#main")).toHaveText("Welcome to Kong Docs");});

We run various quality checks at build time to ensure that the documentation is maintainable.

Some of the checks can be manually marked as approved using labels:

• ci:manual-approve:link-validation - mark link checking as successful. Useful when Netlify returns anHTTP 400 error and the links are validated manually.

Theinclude-check.sh script checks for any files in theapp/_includes folder that depend on apage.* variable (e.g.page.url). This is not compatible with theinclude_cached gem that we use, and so usingpage.* in an include will fail the build.

To run the script locally, open a terminal, navigate to the documentationfolder, and run./include-check.sh. If there is no output, everything issuccessful.

In the following example, we can see thatdeployment-options-k8s.md uses apage.* variable, and that the include is used in thekong-for-kubernetes.md file:

❯ ./include-check.shPage variables must not be usedin includes.Pass themin via include_cached insteadFiles that currently use page.*:File: app/_includes/md/2.5.x/deployment-options-k8s.mdvia:app/enterprise/2.5.x/deployment/installation/kong-for-kubernetes.md

Here are sample contents for those files:

Inkong-for-kubernetes.md:

{% include_cached app/_includes/md/2.5.x/deployment-options-k8s.md %}

Indeployment-options-k8s:

This is an include that uses {{ page.url }}

To resolve this, the two files should be updated to pass in the URL wheninclude_cached is called:

Inkong-for-kubernetes.md:

{% include_cached app/_includes/md/2.5.x/deployment-options-k8s.md url=page.url %}

Indeployment-options-k8s:

This is an include that uses {{ include.url }}

Theinclude_cached gem uses all passed parameters as the cache lookup key, and this ensures that all required permutations of an include file will be generated.

For guidelines on how to write includes and call them in target topics, see theKong Docs contributing guidelines.

When raising a pull request, it's useful to indicate what type of review you're looking for from the team. To help with this, we've added three labels that can be applied:

• review:copyedit: Request for writer review.
• review:general: Review for general accuracy and presentation. Does the doc work? Does it output correctly?
• review:tech: Request for technical review from an SME.

At least one of these labels must be applied to a PR or the build will fail.