/docs.konghq.com

🦍 Source code for docs.konghq.com website

Primary LanguageHTMLMIT LicenseMIT

KONG Website

This repository is the source code for Kong's website. It is a Jekyll website hosted on GitHub pages.

Requirements

Install

gem install bundler
npm install

Running locally

npm start

Deploying

This will deploy to GitHub pages:

npm run deploy

Search

We are using Algolia docsearch for our CE documentation search. The algolia index 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.

Generating the Plugin Development Kit documentation

  • 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, checkout 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

Writing plugin documentation

Plugins are documented under app/plugins. They use a YAML-based system to generate many of the sections on each plugin page. Please look at the existing plugins for examples. Fields are:

  • 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](http://example.com) and not [example][example] pointing to an index at the end).
  • params
    • name - name of the plugin in Kong (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
      • required - true if required, false if optional, semi if 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
      • value_in_examples - if the field is to appear in examples, this is the value to use. A required field with no value_in_examples entry will resort to the one in default.
      • description - description of the field. Use YAML's pipe notation if writing longer Markdown text.