The Kong Developer site uses custom page types and Liquid template tags to render content on a page. This page explains how to write the different page types as well as the different template tags you can use on a page.
Contributing to docs
Uses:
Kong Gateway
Related Documentation
Tags
Page types
The Kong Developer site uses the following different page types:
|
Page type |
Description |
Examples |
|---|---|---|
| Reference | Describes conceptual information as well as reference information, like tables, schemas, or diagrams. | |
| Landing page | Acts as a “sign post” page to direct users to the correct reference or how-to page. These can contain some conceptual or reference material, like feature tables, as long as the goal is to help a user determine which page they should click next. | |
| How-to | Provides an end-to-end tutorial on a use case. In most scenarios, the goal is for users to copy and paste down the page to achieve their goal. All prerequisites are listed in the how-to. A how-to never assumes a user has tools, products, or specific configurations installed. | |
| Autogenerated | Certain reference pages, like schema or configuration references, are autogenerated. |
Core tenets
Contributors should keep these core tenets in mind when creating or editing documentation on the Kong Developer site:
- Every page is page one: Users should be able to answer their question in one page. Don’t separate conceptual information from configuration information, all the reference information about a particular use case should be on one page.
- A how-to should have validation: The majority of how-to pages should be written in a style so that users can copy and paste their way down the page. The final step in a how-to should validate that the how-to, and the product, is functioning as intended.
How-to and reference page blocks
You can use certain Liquid syntax blocks in how-to and reference pages to help render code.
Entity examples
The entity_examples block generates an Gateway entity example, with support for multiple entities in a block. This renders in one format based on the tool you’ve specified in the page metadata.
If you want an entity example rendered in multiple formats, use entity_example.
Entity example
Generates a multi-tab example for an entity with one tab for each tool. For example, the Set up a Consumer section.
If you want to only render an example with one tool, use entity_examples.
Tables
All tables should use the table block and be written in yaml.
Feature table
If you want a table that shows which features are supported or not, use the feature_table block. This turns boolean values into checkmarks or X.
kong.conf table
Renders a list of kong.conf parameters into a table.
Tab groups
You can use navtabs to create tabs with different labels.
Code example:
{% navtabs "deploy-a-license" %}
{% navtab "Admin API" %}
text
{% endnavtab %}
{% navtab "license.json" %}
text
{% endnavtab %}
{% endnavtabs %}
Copied to clipboard!
Rendered output:
Konnect roles
Creates a table with the Konnect roles and descriptions.
Version badge
Displays which version a feature was introduced in. You can use this in headers, tables, and inline text.
No copy code
Prevents users from copying code in a code block.
{:.no-copy-code}
Copied to clipboard!
Render code block/text per deployment type
Displays the code block/text only if the specified deployment type is selected.
Add this tag immediately after a code block.
code for konnect
{: data-deployment-topology="konnect" }
Copied to clipboard!
code for on-prem
{: data-deployment-topology="on-prem" }
Copied to clipboard!
Notes and warnings
You can specify different types of notes and warnings.
How-to validations
The how-to pages typically include a validation step as the final step. This allows users to verify that the steps worked as intended. Validation steps are written in a yaml block to ensure consistency and that they are formatted correctly in the output.
Rate limit check
The rate-limit-check validation creates a code block that users can run to exceed rate limits. For a published example, see the Rate limit a Consumer how-to.
Request check
The request-check validation generates a code block that users can run to validate a request. For a published example, see the Adjust header names in a request how-to.
Unauthorized check
The unauthorized-check generates a code block that users can run to validate that a Consumer is unauthorized. For a published example, see the first code block in the Authenticate Consumers with basic authentication how-to.
Landing page blocks
Landing pages are built in yaml and they use columns that contain blocks to render content. For example, if you have a column that contains one block, the one block will span the page width. If you have a column with two or three blocks, the blocks will equally split the span of the page.
You can also specify a strict number of columns using column_count, forcing the section to always arrange all blocks into that number of columns.
- columns:
column_count: 3
- blocks:
- type: plugin
config:
slug: rate-limiting
- type: plugin
config:
slug: rate-limiting-advanced
Copied to clipboard!
Headers
Any section can have a header.
- Use H1 headers only for page titles.
- Structure headers in sequential order. For example, you can have H1 > H2 > H3 > H2 > H3, but not H1 > H3 > H2.
- header:
type: h1
text: "Konnect Advanced Analytics"
sub_text: A single location for context-rich, business-critical API and AI insights
- header:
type: h2
text: "Traditional mode"
### Structured text
Displays structured text on a landing page.
<!--vale off-->
```yaml
- blocks:
- type: structured_text
config:
header:
text: "Introducing Kong Gateway"
blocks:
- type: text
text: |
Kong Gateway is a lightweight, fast, and flexible cloud-native API gateway. An API gateway is a reverse proxy that lets you manage, configure, and route requests to your APIs.
Kong Gateway runs in front of any RESTful API and can be extended through modules and plugins.
It’s designed to run on decentralized architectures, including hybrid-cloud and multi-cloud deployments.
Copied to clipboard!
Image
Displays an image on a landing page.
- blocks:
- type: image
config:
url: /assets/images/gateway/kong-gateway-overview.svg
alt_text: Diagram of how Kong Gateway works
Copied to clipboard!
Diagram
Displays a Mermaid.js diagram on a landing page.
- blocks:
- type: mermaid
config:
diagram: |
flowchart TD
A(Hybrid
Control Plane)
B(Fully-managed
Control Plane)
C(<img src="/assets/icons/gateway.svg" style="max-height:20px" class="no-image-expand"/> Self-managed
Data Plane nodes
#40;locally-hosted#41;)
D(<img src="/assets/icons/gateway.svg" style="max-height:20px" class="no-image-expand"/> Self-managed
Data Plane nodes
#40;hosted by you in cloud provider#41;)
E(<img src="/assets/icons/gateway.svg" style="max-height:20px" class="no-image-expand"/> Fully-managed
Data Plane nodes
#40;hosted by Kong#41;)
subgraph id1 [Konnect]
A
B
end
A --proxy configuration---> C & D
B --proxy configuration---> E
style id1 stroke-dasharray:3,rx:10,ry:10
Copied to clipboard!
Card
Displays a card/tile that a user can click on a landing page.
- blocks:
- type: card
config:
title: Create a Dev Portal
description: |
Konnect allows you to publish, document, and secure APIs to drive adoption for any developer audience.
You can create multiple Dev Portals based on selected APIs with appropriate visibility and access control settings.
icon: /assets/icons/dev-portal.svg
cta:
url: "https://cloud.konghq.com/portals/create"
Copied to clipboard!
Plugin cards
Displays the title, icon, description, and link to a plugin as a card/tile on a landing page.
- blocks:
- type: plugin
config:
slug: rate-limiting
Copied to clipboard!
Autogenerated how-to list
Displays a list of how-to pages that contain the specified metadata.
-
blocks:
- type: how_to_list
config:
tags:
- rate-limiting
quantity: 5
Copied to clipboard!
Related resources list
Displays a list of related resources.
-
blocks:
- type: related_resources
config:
- text: Protecting Services With Kong Gateway Rate Limiting
type: blog
url: https://konghq.com/blog/engineering/kong-gateway-rate-limiting
Copied to clipboard!
Feature table
Displays a feature table that shows if features are supported or unsupported.
- blocks:
- type: feature_table
config:
columns:
- title: Rate Limiting
key: oss
- title: Rate Limiting Advanced
key: ee
features:
- title: Rate limit based on `consumer`, `consumer-group`, `credential`, `ip` and `service`
oss: true
ee: true
Copied to clipboard!
Table
Displays a regular table that contains text.
- blocks:
- type: table
config:
columns:
- title: Authentication flow or grant
key: auth
- title: Description
key: description
- title: Plugin example configuration
key: example
- title: How-to guide
key: howto
rows:
- auth: Authorization Code flow
description: |
In an Authorization Code flow, clients exchange an authorization code for an access token.
<br><br>
[Workflow diagram →](/plugins/openid-connect/#authorization-code-flow)
example: "[Authorization Code flow example](/plugins/openid-connect/examples/authorization-code/)"
howto: "[OpenID Connect and Keycloak with the auth code flow](/how-to/configure-oidc-with-auth-code-flow/)"
Copied to clipboard!
Tools
The Kong Developer site uses tools to help with automation.
Broken link checker: ignore URls
For more information, see the broken link checker README.
tools/broken-link-checker/config/ignored_targets.json
Copied to clipboard!
Generate kong.conf reference
The kong.conf reference is autogenerated. For more information, see the README.
Sources.yaml
If you are migrating a page from the Kong Docs site to the Kong Developer site, add the path to the dev site file with a list of pages you used from the docs site below it in the sources.yaml file.