You are reviewing the contributing guidelines of docs.konghq.com. If you want to contribute to Kong itself, then please go here.
Contributing to docs.konghq.com
Hello, and welcome! Whether you are looking for help, trying to report a bug, thinking about getting involved in the project or about to submit a patch, this document is for you!
Consult the Table of Contents below, and jump to the desired section.
Table of Contents
- Where to seek help?
- Where to report bugs?
- Contributing to Kong documentation and the Kong Hub
Where to seek help?
Consult the Kong Contributing Guideline for an overview of the communication channels at your disposal.
Where to report bugs?
If the bug is related to Kong itself, please refer to the Kong Contributing Guideline instead.
Contributing to Kong documentation and the Kong Hub
Improving the documentation is a most welcome form of contribution to the Kong community! You are encouraged to suggest edits, improvements, or fix any typo you may find on this website. Please read the below section about submitting a patch.
Adding and improving listings in the Kong Hub is also encouraged! Please read the below section about Kong Hub contributions
If you wish to contribute to Kong itself (as opposed to the documentation website), then please consult the Kong Contributing Guideline instead.
When contributing, be aware of a few things:
- Documentation for Kong Hub listings, which includes all Kong Inc.-published
and community-published plugins and integrations, lives in the
app/_data/extensionsdirectories. Versioning is optional, and thus potentially inconsistent, for this part of the documentation.
- Kong documentation lives in
app/x.x.xand Kong Enterprise documentation lives in
app/enterprise/. These parts of the documentation are versioned. When proposing a change in these parts of the documentation, consider proposing the change for older versions as well. Example: if you fix a typo in
app/docs/0.10.x/configuration.md, this typo may also be present in
Submitting a patch
Feel free to contribute fixes or minor features, we love to receive Pull Requests! If you are planning to develop a larger feature, come talk to us first in Kong Nation.
When contributing, please follow the guidelines provided in this document. They will cover topics such as the commit message format to use or how to run the linter.
Once you have read them, and you are ready to submit your Pull Request, be sure to verify a few things:
- Your commit history is clean: changes are atomic and the git message format was respected
- Rebase your work on top of the base branch (seek help online on how to use
git rebase; this is important to ensure your commit history is clean and linear)
- The linting is succeeding: run
npm run test(see the development documentation for additional details)
If the above guidelines are respected, your Pull Request has all its chances to be considered and will be reviewed by a maintainer.
If you are asked to update your patch by a reviewer, please do so! Remember: you are responsible for pushing your patch forward. If you contributed it, you are probably the one in need of it. You must be prepared to apply changes to it if necessary.
If your Pull Request was accepted, congratulations! You are now an official contributor of docs.konghq.com and member of the Kong community.
Your changes will be deployed as soon as a maintainer gets a chance to trigger a build, which should generally happen right after your patch was merged.
Kong Hub contributions
If you are planning on producing a new Kong plugin or integration, with the intent to list it in the Kong Hub, you are encouraged to have a quick call with Kong's Director of Ecosystem, Cooper Marcus - book a time, or email him at firstname.lastname@example.org.
Adding a new listing to the Kong Hub may be proposed by:
- Clone this repo
- Create a publisher directory at
_app/_hub/, such as
_app/_hub/your-github-handle(if you are contributing as an individual) or
_app/_hub/company-name(if you are contributing as a company). See other Kong Hub listings for examples of publisher names.
- Create a subdirectory for your extension within your publisher directory -
- Copy the
/app/_hub/_init/my-extension/index.mdfile into your extension's subdirectory. If you are publishing a single version of your extension, which is typical to start with, then the file name
- Edit your
index.mdfile based on the guidance in comments in that file - you'll find lots of helpful examples in other extension's files. If you are documenting a Kong plugin, be sure to see the next section.
- If you have a custom logo, add a square-format PNG file to
/app/_assets/images/icons/hub/- the filename of your image should be
publisher_extensionusing the "publisher" and "extension" name from step 2. Custom logos are optional. If you don't have a custom logo, please duplicate an existing default logo file, and rename it as noted above.
- Be sure to run the docs site locally per the instructions in
the README - you should find your Hub contribution listed at
- Once you are happy with your listing, make a Pull Request to add it to the Kong Hub. Having trouble, or have questions?
Kong staff will review your PR, suggest improvements and adjustments as necessary, and once approved, will merge and deploy your Kong Hub addition!
Writing plugin documentation
Plugins are documented as extensions under
app/_hub/ - please look at
the existing plugins for examples, and see additional advice in
description- text to be added in the Description section. Use YAML's pipe notation to write multi-paragraph text. Note that due to the order that data is generated, you may not use forward-references in links (e.g. use
[example][example]pointing to an index at the end).
desc(string, required) - a short, one-line description of the extension.
type(array, required) - what kind of extension this is:
integrationare supported at this time, though more types will be considered.
name- name of the plugin as it is referred to in Kong's config and Kong's Admin API (not always the same spelling as the page name)
api_id- boolean - whether this plugin can be applied to an API. Affects generation of examples and config table.
route_id- boolean - whether this plugin can be applied to a Route. Affects generation of examples and config table.
service_id- boolean - whether this plugin can be applied to a Service. Affects generation of examples and config table.
consumer_id- boolean - whether this plugin can be applied to a Consumer. Affects generation of examples and config table.
config- the configuration table. Each entry is a configuration item with the following fields:
name- the field name as read by Kong
semiif semi-required (required depending on other fields)
default- the default value. If using Markdown (e.g. to make values appear type-written), wrap it in double-quotes like
value_in_examples- if the field is to appear in examples, this is the value to use. A required field with no
value_in_examplesentry will resort to the one in
description- description of the field. Use YAML's pipe notation if writing longer Markdown text.
In this repository,
master represents the current state of the website, and
should constantly be deployed. Branch off of this branch for local development.
If you have write access to the GitHub repository, please follow the following naming scheme when pushing your branch(es):
docs/<ce|ee>-foo-barfor updates to contents of the documentation (Markdown files), README.md, or this file
fix/foo-barfor website bug fixes (not including typos and other fixes to the documentation itself, see the Type section below)
When submitting patches, it is important that you organize your commits in logical units of work. You are free to propose a patch with one or many commits, as long as their atomicity is respected. This means that no unrelated changes should be included in a commit.
For example: you are writing a patch to fix a bug, but in your endeavour, you spot another bug. Do not fix both bugs in the same commit!. Finish your work on the initial bug, propose your patch, and come back to the second bug later on. This is also valid for unrelated style fixes, refactorings, etc...
You should use your best judgement when facing such decisions. A good approach for this is to put yourself in the shoes of the person who will review your patch: will they understand your changes and reasoning just by reading your commit history? Will they find unrelated changes in a particular commit? They shouldn't!
Writing meaningful commit messages that follow our commit message format will also help you respect this mantra (see the below section).
Commit message format
To maintain a healthy Git history, we ask of you that you write your commit messages as follows:
- The tense of your message must be present
- Your message must be prefixed by a type, and a scope
- The header of your message should not be longer than 50 characters
- A blank line should be included between the header and the body
- The body of your message should not contain lines longer than 72 characters
Here is a template of what your commit message should look like:
<type>(<scope>) <subject> <BLANK LINE> <body> <BLANK LINE> <footer>
The type of your commit indicates what type of change this commit is about. The accepted types are:
- docs: Changes made to any static content files associated with Kong, Kong Enterprise, and Kong Hub documentation (including typo fixes), the README.md or this file
- style: CSS fixes, formatting, missing semi colons,
- refactor: A code change that neither fixes a bug nor adds a feature, and
is too big to be considered
- chore: Maintenance changes related to code cleaning that isn't considered part of a refactor, build process updates, dependency bumps, or auxiliary tools and libraries updates (npm modules, Travis-ci, etc...)
The scope is the part of the codebase that is affected by your change. Choosing it is at your discretion, but here are some of the most frequent ones:
<ce or ee>/<section>: A change that affects Kong docs or Kong Enterprise docs and specifies which section.
admin: Changes related to the Admin API documentation
proxy: Changes related to the proxy documentation
conf: Changes related to the configuration file documentation (new values, improvements...)
<plugin-or-extension-name>: A change to any of the listings in the Kong Hub. This could be
*: When the change affects too many parts of the codebase at once (this should be rare and avoided)
Here are a few examples of good commit messages to take inspiration from:
docs(ee/dev-portal) cleanup installation instructions * add ports exposed for Dev Portal functionality * use relative links and version them when necessary From #623
As mentioned in the guidelines, to submit a patch, the linter must succeed. You can run the linter like so:
$ npm run test
Contributing images, videos, etc
Binary files like images and videos should not be included in your pull request, with the exception of custom icons for the Kong Hub - any request including them will be rejected.
- Include the HTML necessary to display your binary file in your code
- In place of the link to the binary file, use
- Email your binary files to email@example.com, and include a link to your pull request
- Kong staff will host your binary files on our CDN, and will replace the
FIXMEs in your code with URLs of the binaries
Table of Contents generator
Almost all pages have an automatic Table of Contents (ToC) added to the top of the page, courtesy of https://github.com/Kong/docs.konghq.com/pull/920
To inhibit the automatic addition of ToC, add the following to the front-matter
This ToC generator depends on headings being correctly coded in the markdown portion of the doc site files. If a page has an incorrectly-formatted ToC, be sure to check:
- Heading levels must be correctly nested. Thus, heading levels like this:
# Heading Level 1 ## Sub-heading Level 2 #### Sub-sub-sub-heading Level 4
will cause a broken ToC, and should be corrected to:
# Heading Level 1 ## Sub-heading Level 2 ### Sub-sub-heading Level 3
Proudly wear your T-shirt and show it to us by tagging @thekonginc on Twitter!