Skip to content
|
search
Contribution guidelines

Conditional rendering

The Kong docs support conditional rendering based on the following:

  • Product
  • Product version

Conditionally render content by product

If you have content that needs to be reused between multiple products, you can conditionally render parts of that for a specific product:

This sentence is visible for every product that the content is used in.

{% unless page.edition == "konnect" %}
This will be hidden for Konnect.
{% endunless %}

{% if page.edition == "gateway" %}
This will show only for Kong Gateway.
{% endif %}

You can find all the supported editions in the app/_data/kong_versions.yml metadata file.

Conditionally render content by version

You can use conditional rendering by version for any content in the app/_src or app/_hub directories.

As we add new functionality, we want content on a page to be displayed only for specific releases of a product. You can use the if_version block for this, or if_plugin_version for any content in the Plugin Hub.

  • if_version is used by Kong Gateway, Kong Mesh, Kubernetes Ingress Controller, and decK documentation.
  • if_plugin_version can only be used for plugin documentation in the app/_hub directory.

if_version and if_plugin_version support the following filters:

  • eq: Render content that equals the provided version.
  • gte: Render content that is equal or greater than the provided version.
  • lte: Render content that is equal or less than the provided version.

For example, eq displays content for only one specific version:

{% if_version eq:1.11.x %}
This will only show for version 1.11.x
{% endif_version %}

Or for a plugin:

{% if_plugin_version eq:2.8.x %}
This will only show for plugin version 2.8.x
{% endif_plugin_version %}

Greater than (gte) and less than (lte) are inclusive of the version provided:

{% if_version gte:1.11.x %}
This will only show for version 1.11.x and later (1.12.x, 2.0.0 etc)
{% endif_version %}

{% if_plugin_version lte:2.8.x %}
This will only show for plugin version 2.8.x and earlier (2.7.x, 2.6.x etc)
{% endif_plugin_version %}

{% if_version gte:1.11.x lte:1.19.x %}
This will show for versions 1.11.x through 1.19.x, inclusive
{% endif_version %}

Table rows

When working with tables, you can set a conditional filter for a given row. The filter expects new lines before and after if_version or if_plugin_version:

| Name  | One         | Two    |
|-------|-------------|--------|
| Test1 | Works       | Shows  |

{% if_version gte: 1.11.x %}
| Test2 | Conditional | Hidden |
{% endif_version %}

| Test1 | Works       | Shows  |

The above will be rendered as a single table.

Inline content

If you want to conditionally render content in a sentence, you can use if_version or if_plugin_version and specify inline:true:

Hello {% if_version eq:1.0.0 inline:true %}everyone in the {% endif_version %} world.

Hello {% if_plugin_version lte:2.8.x inline:true %}everyone in the {% endif_plugin_version %} world.

Front matter

You may want to set values in a page’s front matter conditionally. You can do this using overrides:

---
title: Page Here
alpha: false # This is the default, but is here for completeness

overrides:
  alpha:
    true:
      gte: 2.3.x
      lte: 2.5.x
---

In the above example, versions 2.3.x, 2.4.x and 2.5.x will have alpha: true, and all other versions will have alpha: false.

You can set the key to any scalar value. Here’s an example using strings to switch something from “Private Beta” (2.8.x and earlier) to GA (anything later than this).

---
title: Another Page
availability: GA

overrides:
  availability:
    Private Beta:
      lte: 2.8.x
---

Plugin parameters

Generated parameters for files in the app/_hub directory can specify minimum_version and maximum_version fields. Here’s an example where access_token_name will only be shown for versions 1.4.0 to 1.7.0, while demo_field will always be shown:

params:
  name: sample-plugin
  service_id: true
  route_id: true
  consumer_id: false
  dbless_compatible: "yes"
  manager_examples: false
  konnect_examples: false
  config:
    - name: demo_field
      required: true
      default: "`access_token`"
      datatype: string
      description: This is a demo_field
    - name: access_token_name
      required: true
      default: "`access_token`"
      datatype: array of string elements
      description: This is a description
      minimum_version: "1.4.0"
      maximum_version: "1.7.0"

Both minimum_version and maximum_version are optional.

You can do the same for plugin protocols:

params:
  protocols:
    - name: http
    - name: https
    - name: grpc
    - name: grpcs
    - name: ws
      minimum_version: "3.0.x"
    - name: wss
      minimum_version: "3.0.x"