KONG's Documentation Website
This repository is the source code for Kong's documentation website. It is a Jekyll website hosted on GitHub pages.
Not sure where to start? Head on over to the issues
tab to and look for the good first issue
label. These are issues Kong has identified as beginner friendly. Many of these can be addressed through Github and do not require pulling the repository and building locally.
Develop Locally with Docker
make install-prerequisites
make develop
Running a Local Build with Docker
Install tools:
make install
Run the build:
make run
Check the build output at http://localhost:3000.
Testing Links with Docker
make check-links
Develop Locally without Docker
Prerequisites
Install
gem install bundler
npm install
Running
npm start
Search
Documentation for our open-source projects uses Algolia for search. The Algolia index for OSS docs is maintained by Algolia through their docsearch service. Their scraper runs every 24 hours. The config used by the scraper is open source for docs.konghq.com and can be found here. To update the scraper config, you can submit a pull request to the config. To test a config change locally, you will need to run their open source scraper against your own scraper to test out config changes.
The rest of the Kong documentation uses paid Algolia indices, which auto-update every 24 hours via a github action here.
Versioning the docs
The following instructions apply to the Kong Gateway OSS docs. For enterprise docs, see the instructions on the docs wiki.
Creating a new community doc release version
-
Pull down the master branch of this repo and create a release branch (
release/<version>
):$ cd docs.konghq.com $ git pull master $ git checkout -b release/2.4
-
Copy the following doc folders for Kong Gateway (OSS):
-
Copy the latest
app/gateway-oss/
version folder and all of its contents. Rename the folder to the new major or minor version, withx
for the patch level.For example, copy
app/gateway-oss/2.3.x
and rename toapp/gateway-oss/2.4.x
. -
Copy the latest
app/getting-started-guide/
version folder and rename it to the new version. -
Copy the latest
app/_includes/md/
version folder and rename it to the new version.
-
-
Add the newest CE version to
app/_data/kong_versions.yml
:-
Copy the previous version section, which looks like the following:
release: "2.3.x" version: "2.3.2" edition: "gateway-oss" luarocks_version: "2.3.2-0" dependencies: luajit: "2.1.0-beta3" luarocks: "3.4.0" cassandra: "3.x.x" postgres: "9.5+" openresty: "1.17.8.2" openssl: "1.1.1i" libyaml: "0.2.5" pcre: "8.44"
Update
release
,version
, and anydependencies
, if applicable. -
Do the same for
getting-started-guide
, copying the latest version, which looks like the following:release: "2.3.x" version: "2.3" edition: "getting-started-guide"
-
-
Update the latest version in the full site Algolia configuration file:
-
Open
/algolia/config-full-docs.json
-
In the
start_urls
section, update thegateway-oss
URL to the latestx.x.x
version:"url": "https://docs.konghq.com/gateway-oss/2.3.x/"
-
-
Commit and push release branch to GitHub.
Generating the PDK, Admin API, CLI, and Configuration Documentation
The PDK docs, Admin API docs, cli.md
and configuration.md
for each release are generated from the Kong source code.
To generate them, go to the Kong/kong
repo and run:
scripts/autodoc <docs-folder> <kong-version>
For example:
cd /path/to/kong
scripts/autodoc ../docs.konghq.com 2.3.x
This example assumes that the Kong/docs.konghq.com
repo is cloned into the
same directory as the Kong/kong
repo, and that you want to generate the docs
for version 2.3.x
. Adjust the paths and version as needed.
Once everything is generated, review, open a branch with the changes, send a pull request, and review the changes.
You usually want to open a PR against a release/*
branch. For example, in the
example above the branch was release/2.3
.
cd docs.konghq.com
git fetch --all
git checkout release/2.3
git checkout -b release/2.3-autodocos
git add -A .
git commit -m "docs(2.3.x) add autodocs"
git push
Then open a pull request against release/2.3
.
Listing Your Extension in the Plugin Hub
We encourage developers to list their Kong Gateway plugins in the Plugin Hub with documentation hosted on the Kong docs website for ready access.
See CONTRIBUTING for more information.