Style guide

Uses: Kong Gateway

Language

The Kong docs use American English (US English).

✅ Do use (American English)	❌ Don’t use (other variations)
The response should look like…	The response shall look like…
In the previous section, you learned…	In the previous section, you learnt…
Color, recognize, analyze	Colour, recognise, analyse
While	Whilst

At Kong, we try to keep our tone conversational, but not at the expense of clarity. We keep language simple and concise, take things seriously when we need to, and keep our readers in mind in whatever we write.

Prefer plain, direct language over formal or technical-sounding alternatives:

✅ Do use	❌ Don’t use
Run the program.	Execute the program.
Use the Admin API.	Utilize the Admin API.
Open the link to do the thing.	Open the link in order to do the thing.
In the open tab, do the thing.	In the open tab that appears, do the thing. In the open tab that displays, do the thing.
Clearly refer to subjects. For example: “Once you have added the inputs section, …”	Avoid generic pronouns. For example, don’t say: “Once you have added this, …”

Active voice

Use active voice, and avoid passive voice.

With active voice, the subject performs an action. With passive voice, the action is performed upon the subject:

✅ Active	❌ Passive
The plugin applies rate limiting to consumers.	Rate limits are applied to consumers by the plugin.
You can explore the API using a browser.	The API can be explored using a browser.
The YAML file specifies the replica count.	The replica count is specified in the YAML file.

There are exceptions. You might use passive voice when the subject is genuinely passive and isn’t performing any action. For example: “The CA provider’s external account can be registered automatically.” In this sentence, the account isn’t doing anything, so passive voice is appropriate.

Present tense for references

Whenever possible, use present tense instead of past or future tense for documentation.

✅ Do use	❌ Don’t use
This `command` starts a proxy.	This `command` will start a proxy.
This `command` starts a proxy.	This `command` has started a proxy.

Just like for active voice, there are exceptions here too. In how-to guides, we use a more natural tone, so using “will” in phrases like “You’ll see this result on the screen” is completely fine.

Contractions

Don’t be afraid to use contractions (can’t, isn’t, you’ll, and so on). They contribute to our conversational tone.

There are exceptions. Omit contractions when aiming for a more serious tone, such as in a warning or caution:

Contraction (informational): “This plugin isn’t available in Konnect.”
No contraction (warning): “Do not use this plugin in Konnect because it will break your configuration.”

Latin phrases

Don’t use Latin abbreviations or phrases. Use the English equivalent instead.

✅ Do use	❌ Don’t use
For example, …	e.g., ex., …
That is, …	i.e., …
So (or therefore), …	Ergo, …

Bias-free language

Use gender-neutral and unbiased language.

✅ Do use	❌ Don’t use
Denylist, allowlist	Blacklist, whitelist
Main branch	Master branch
Neutral pronouns (you, they/them)	Gendered pronouns (he/his, she/her)

Recommendations

A recommendation should:

Apply to most users in the given context — it’s not a general suggestion
Always include a reason so readers understand why it’s recommended

Use the phrase “we recommend” rather than “Kong recommends” or “it is recommended”:

✅ Do use	❌ Don’t use
We recommend using an access token because it’s more secure.	Kong recommends using an access token.
We don’t recommend storing a password in plaintext because it’s not secure.	It is recommended that you use an access token.

Grammar and syntax

Punctuation

Commas and periods always go inside quotation marks. Colons, semicolons, and dashes go outside.

For example: “There was a storm last night,” Paul said.

List punctuation

Use end punctuation when list items are full sentences:

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative configuration, including:

Setting a target’s health status in the load balancer.

Validating configurations against schemas.

Uploading the declarative configuration using the /config endpoint.

Don’t use end punctuation when list items are fragments that complete the introductory sentence:

Kong Mesh enables the microservices transformation with:

Out-of-the-box service connectivity and discovery

Zero-trust security

Traffic reliability

Global observability across all traffic

Headings and page titles

Be descriptive. A heading should tell readers what they’ll find in the section or on the page — not just label it generically.

✅ Do use	❌ Don’t use
What is Kong Gateway?	Overview
Query frequency and precision	Query behavior

Use sentence case for section headings. Capitalize only the first word and proper nouns — not every word:

✅ Do use	❌ Don’t use
Understanding traffic flow in Kong Gateway	Understanding Traffic Flow in Kong Gateway
Get started with the Request Transformer Advanced plugin	Get Started with the Request Transformer Advanced Plugin

Capitalization

When documenting a user interface (UI), follow its formatting. If a term is capitalized in the UI and you’re referring to that specific UI element, capitalize it in the documentation too.

Terms that are capitalized

The following terms should be capitalized:

Gateway API entity names:

Certificate
Consumer
Plugin
Route
Service (Gateway Service)
Target
Upstream
Vault

The following terms should not be capitalized. They should be lowercase unless at the start of a sentence:

control plane
data plane
application
database
developer
hybrid mode
service mesh

Plugin name capitalization

Capitalize the plugin name but not the word plugin. For example, “Rate Limiting plugin”.
Don’t capitalize in code. For example, rate-limiting.
Don’t capitalize if you’re referring to the concept rather than the plugin itself. For example: “Set up rate limiting in Kong Gateway with the Rate Limiting plugin.”

Formatting

Placeholder and example values

The type of placeholder you use depends on context:

Generic placeholder values — in most situations (such as plugin parameters, YAML examples, or Kong configuration), use all-caps text with underscores between words.

For example: service: SERVICE_NAME
Placeholders in API URLs or OpenAPI specs — enclose in { } and use the parameter name defined by the API or spec, per Swagger guidelines.

For example: /services/{serviceId}/plugins
Hostnames and example URLs:
- For guides with examples intended to be run as-is, use localhost as the domain or $KONNECT_PROXY_URL for Konnect documentation.
  
  For example: curl -i -X GET https://localhost:8001/services
  
  A reader following this guide with Kong Gateway running locally can copy and paste the command directly into a terminal.
- For illustrative examples that are not intended to be run as-is, use example or example.com.
  
  For example: user@example.com or https://example.okta.admin.com
Path parameters — always denote with curly braces {}.

For example: http://localhost:8001/services/{serviceId|serviceName}/routes/{routeId|routeName}

Inline placeholders

If you’re adding a placeholder inline in a sentence, enclose it in single backticks: `EXAMPLE_TEXT`

Code formatting

Separate commands from their output. Put each in its own code block. Use {:.no-copy-code} directly under an output if users won’t need to copy the output.
Include properly formatted code comments.
For long commands, split the code block across multiple lines using \ to avoid horizontal scrolling.
Never include more than one command in a single code block.
Use yaml liquid blocks for code when it’s supported (for example, entity_example, konnect_api_request). If there are no corresponding liquid blocks, always set a language for code blocks (for example, bash, yaml) to enable syntax highlighting.
Do not use the command prompt marker ($) in code snippets.

Icons

For inline icons in prose or tables, use SVG files from the /app/assets/icons/ directory. Browse the directory to find the icon you need, then reference it with a relative path.

Documenting third-party tools

When a how-to guide requires a third-party tool (such as an identity provider, cloud service, or external API) to be configured in a specific way to work with Kong, include complete setup instructions rather than linking out to third-party documentation and expecting readers to figure it out.

In most cases, the third-party instructions should be a prerequisite. Write the prerequisite steps in a file under app/_includes/prereqs/ and include it at the top of the how-to. This keeps the how-to self-contained: readers can follow the entire guide in one place without switching between multiple sources.

For an example, see app/_includes/prereqs/gemini.md, which walks users through getting a Gemini API key from Google Cloud before the main tutorial begins.

In certain cases, the third-party instructions should be in the main how-to body. For example, if users need to update a routing table in AWS after they’ve set up their Dedicated Cloud Gateway network or if they need to approve a Catalog integration in the third-party provider after they configure it in Catalog.

Writing prerequisite instructions

When writing third-party setup steps:

Include every required step, in order. Don’t assume users have already completed any part of the setup.
Use action-oriented steps: “Go to…”, “Click…”, “Copy the…”.
Export any required values as environment variables so readers can reference them in later commands without having to look them up again.
Keep instructions generic enough to survive minor UI changes. Refer to UI elements by their label only, not by their location or visual appearance.

Pitfalls to avoid

Third-party UIs change frequently. To reduce maintenance overhead:

Do not include screenshots of third-party UIs.
Refer to UI elements by their label only — not their color, position, or visual style:

✅ Do use	❌ Don’t use
Click Add.	Click the blue Add button in the top-right corner.
Enter the API key provided by your API provider.	Enter the API key found in the Security tab under API Settings.

Links

Write descriptive link text that tells readers what they’ll find when they click. Don’t use vague phrases like “click here” or “read more”.

✅ Do use	❌ Don’t use
For more information, see the style guide.	For more information, click here.
Learn about content best practices in the Kong style guide.	Learn about content best practices here.