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.
make develop
make check-links
gem install bundler
npm install
npm start
We are using Algolia docsearch for our documentation search. The algolia index for Kong 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 Enterprise documentation uses paid algolia indices, which auto-update every 24 hours via a github action here
- Have a local clone of Kong.
- Install Luarocks (comes with Kong).
- Install
ldoc
using Luarocks:luarocks install ldoc 1.4.6
- In the Kong repository, check out the desired branch/tag/release.
- Run:
KONG_PATH=path/to/your/kong/folder KONG_VERSION=0.14.x gulp pdk-docs
- This command will attempt to:
- Obtain an updated list of modules from your local PDK and put it inside your nav file.
- Generate documentation for all the modules in your PDK (where possible) and put in a folder inside your version docs.
- Make sure that the
resty
andluajit
executables are in your$PATH
(installing kong should install them). - Several Lua rocks are needed. The easiest way to get them all is to execute
make dev
in the Kong folder - Have a local clone of Kong.
- In the Kong repository, check out the desired branch/tag/release.
- To generate the Admin API docs:
- Run:
KONG_PATH=path/to/your/kong/folder KONG_VERSION=0.14.x gulp admin-api-docs
- This command will attempt to:
- Compare Kong's schemas and Admin API routes with the contents of the file
autodoc-admin-api/data.lua
and error out if there's any mismatches or missing data. - If no errors were found, a new
admin-api.md
file will be generated in the path corresponding to the provided KONG_VERSION.
- Compare Kong's schemas and Admin API routes with the contents of the file
- Run:
- To generate the CLI docs:
- Run:
KONG_PATH=path/to/your/kong/folder KONG_VERSION=0.14.x gulp cli-docs
- This command will:
- Extract the output of the
--help
for everykong
CLI subcommand - Generate a new
cli.md
in the path corresponding to the provided KONG_VERSION.
- Extract the output of the
- Run:
- To generate the Configuration docs:
- Run:
KONG_PATH=path/to/your/kong/folder KONG_VERSION=0.14.x gulp conf-docs
- This command will:
- Parse Kong's
kong.conf.default
file and extract sections, variable names, descriptions, and default values - Write those down inside a
configuration.md
file in the path matching KONG_VERSION. - The command will completely overwrite the file, including text before and after the list of vars.
- The data used for the before/after parts can be found in
autodoc-conf/data.lua
- Parse Kong's
- Run:
We encourage developers to list their Kong plugins and integrations (which we refer to collectively as "extensions") in the Kong Hub with documentation hosted on the Kong website for ready access.
See CONTRIBUTING for more information.