このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Developer Portal Structure and File Types
The Kong Portal templates have been completely revamped to allow for easier customization, clearer separation of concerns between content and layouts, and more powerful hooks into Kong lifecycle/data. Under the hood, we have implemented a flat file CMS built on top of the https://github.com/bungle/lua-resty-template
library. This system should feel familiar for anyone who has worked with projects like jekyll
, kirby cms
, or vuepress
in the past.
Note: To follow along with this guide, it is best to clone the kong-portal-templates repo and check out the
master
branch. This guide makes the assumption that you are working within a single workspace (the templates repo can host many different sets of portal files per workspace). Navigate to theworkspaces/default
directory from root to view the default workspaces portal files.
Directory Structure
Navigate to workspaces/default
from the kong-portal-templates
root directory to access the default portals template files. The relative file structure in this directory directly maps to the file path
schema attribute. (content/homepage.txt
here maps to content/homepage.txt
in Kong).
From workspaces/default
, you can see the different elements that make up a single instance of the kong developer portal:
-
content/
- The content directory contains files that determine both site structure of the Kong Dev Portal as well as the dynamic content that renders within each page.
-
specs/
- Specs are similar to content in that they contain the data needed to render dynamic content on the page. In the case of
specs
, the files contain valid OAS or Swagger to be rendered as a spec.
- Specs are similar to content in that they contain the data needed to render dynamic content on the page. In the case of
-
themes/
- The theme directory contains different themes to be applied to the content of the portal. Each theme contains HTML templates, assets, and a config file that sets global styles available to the theme.
-
portal.conf.yaml
- This config file determines which theme the portal uses to render, the name of the portal, as well configuration for special behavior such as redirect paths for user actions like login/logout.
-
router.conf.yaml (optional)
- This optional config file overrides the portals default routing system with hardcoded values. This is useful for implementing single page applications, as well as for setting a static site structure.
Portal Configuration File
Path
-
format:
portal.conf.yaml
-
file extensions:
.yaml
Description
The Portal Configuration File determines which theme the portal uses to render, the name of the portal, as well as configuration for special behavior such as redirect paths for user actions like login/logout. It is required in the root of every portal. There can only be one Portal Configuration File, it must be named portal.conf.yaml
, and it must be a direct child of the root directory.
Example
name: Kong Portal
theme:
name: light-theme
redirect:
unauthenticated: login
unauthorized: unauthorized
login: dashboard
logout: ''
pending_approval: ''
pending_email_verification: ''
collections:
posts:
output: true
route: /:stub/:collection/:name
layout: post.html
-
name
:- required: true
-
type:
string
- description: The name attribute is used for meta information, such as setting a title for your portal in the browser tab.
-
example:
Kong Portal
-
theme
- required: true
-
type:
object
- description: The theme object is used for declaring which theme you would like your portal to render, as well as theme style overrides. While the overrides are not required, declaring which theme you would like to use is.
-
redirect
- required: true
-
type:
object
- description: The redirect object informs kong how to redirect the user after certain actions. If one of these values is not set, Kong serves a default template based off of the action. Each key represents the name of the action taking place, the value represents the route to which the application redirects the user.
-
collections
- required: false
-
type:
object
- description: Collections are a powerful tool enabling you to render sets of content as a group. Content rendered as a collection share a configurable route pattern, as well as a layout. For more information check out the collections section of our Working with Templates guide.
Router Configuration File (Optional)
Path
-
format:
router.conf.yaml
-
file extensions:
.yaml
Description
This optional config file overrides the portals default routing system with hardcoded values. This is useful for implementing single page applications, as well as for setting a static site structure. There can only be one Router Configuration File, it must be named router.conf.yaml
, and it must be a direct child of the root directory.
Example
The router.conf.yaml
file expects sets of key-value pairs. The key should be the route you want to set; the value should be the content file path you want that route to resolve to. Routes should begin with a backslash. /*
is a reserved route and acts as a catchall/wildcard. If the requested route is not explicitly defined in the config file, the portal will resolve to the wildcard route if present.
/*: content/index.txt
/about: content/about/index.txt
/dashboard: content/dashboard.txt
Content Files
Path
-
format:
content/**/*
-
file extensions:
.txt
,.md
,.html
,.yaml
,.json
Description
Content files establish portal site structure, as well as provide its accompanying HTML layout with metadata and dynamic content at the time of render. Content files can be nested in as many subdirectories as desired as long as the parent directory is content/
.
In addition to providing metainfo and content for the current page at time of render, content files determine the path at which a piece of content can be accessed in the browser.
Content Path | Portal URL |
---|---|
content/index.txt |
http://portal_gui_url/ |
content/about.txt |
http://portal_gui_url/about |
content/documentation/index.txt |
http://portal_gui_url/documentation |
content/documentation/spec_one.txt |
http://portal_gui_url/documentation/spec_one |
Contents
---
title: homepage
layout: homepage.html
readable_by: [red, blue]
---
Welcome to the homepage!
File contents can be broken down into two parts: headmatter
and body
.
headmatter
The first thing to notice in the example files contents are the two sets of ---
delimiters at the start. The text contained within these markers is called headmatter
and always gets parsed and validated as valid yaml
. headmatter
contains information necessary for a file to render successfully, as well as any information you would like to access within a template. Kong parses any valid yaml
key-value pair and becomes available within the content’s corresponding HTML template. There are a few reserved attributes that have special meaning to Kong at the time of render:
-
title
:- required: false
-
type:
string
- description: The title attribute is not necessary but is recommended. When set, this will set the title of a page in the browser tab.
-
example:
homepage
-
layout
- required: true
-
type:
string
-
description: The layout attribute is required for each piece of content, and determines what HTML layout to use in order to render the page. This attribute assumes a root of the current themes layout directory (
themes/<theme-name>/layouts
). -
example:
bio.html
orteam/about.html
-
readable_by
- required: false
-
type:
array
(multiple),string
(singular) -
description: The optional
readable_by
attribute determines which developers can access a piece of content. In the case of the example above, only developers with rbac roles of “red” or “blue” may access the/homepage
route. -
example:
[red, blue]
(multiple),red
(singular)
-
route
- required: false
-
type:
string
- description: This optional attribute overrides the generated route Kong assigns to content, and replaces it with the route included here.
-
example:
route: /example/dog
renders the example page above at<url>/example/dog
instead of the autogenerated/homepage
route.
-
output
- required: false
-
type:
boolean
-
default:
true
-
description: This optional attribute is
true
by default and determines whether a piece of content should be rendered. No route or page gets created when this value is set tofalse
.
-
stub
- required: false
-
type:
string
-
description: Used by
collection
config to determine custom routing. You can read more about Collections in the collections section of the working with templates guide.
body
The information located under headmatter represents the content body. Body content is freeform and gets parsed as by the file extension included in the file path. In the case of the example above, the file is .txt
and is available in the template as such.
Spec Files
Path
-
format:
specs/**/*
-
file extensions:
.yaml
,.json
Description
Specs are similar to content
files in that they provide the dynamic data needed to render a page, as well as any metadata a user wants to provide as headmatter
. The format in which these are provided to the Portal differs from content
files, which can be seen in the example below.
It is recommended to keep spec folder structure flat. Spec files must be valid OAS or Swagger
.yaml
/.yml
or.json
files.
Contents
swagger: "2.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
host: petstore.swagger.io
basePath: /v1
x-headmatter
- key1: val1
- key2: val2
...
Spec file contents themselves should be valid OAS or Swagger specifications. If you want
to inject headmatter into the specification, you can do so by including an x-headmatter
key to the root of the spec object. This may be useful if you wanted to, for example,
provide your own renderer template via x-headmatter.layout
or override the spec’s default
route via x-headmatter.route
.
Example:
swagger: "2.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
host: petstore.swagger.io
basePath: /v1
x-headmatter:
layout: custom/my-spec-renderer.html <- Custom Layout
route: my-special-route/myfirstspec <- Custom Route
...
Specs are a collection, meaning their layout
and route
are determined by the
portal configuration and not the file itself. Specs are rendered by default with
the system/spec-renderer.html
layout, under the route pattern /documentation/:name
,
where :name
is the name of the particular spec file. So a spec with a path of
specs/myfirstspec.json
renders in the portal as /documentation/myfirstspec
.
If you want to overwrite the hardcoded spec collection config, you can do so by
including your own in portal.conf.yaml
. Check out the Collections section of
our Working with Templates
guide to learn more.
You can also use the Portal Files API
to POST
, GET
, PATCH
, and DELETE
content, spec, and theme files.
Theme Files
Themes Directory Structure
The theme directory contains different instances of portal themes, each one of which determines the look and feel of the developer portal via HTML/CSS/JS. Which theme is used at time of render is determined by setting theme.name
within portal.conf.yaml
. Setting theme.name
to best-theme
causes the portal to load theme files under themes/best-theme/**
.
Each theme file is composed of a few different folders:
-
assets/
- The assets directory contains static assets that layouts/partials will reference at time of render. Includes CSS, JS, font, and image files.
-
layouts/
- The layouts directory contains HTML page templates that
content
reference via thelayout
attribute in headmatter (seecontent
section).
- The layouts directory contains HTML page templates that
-
partials/
- The partials directory contains HTML partials to be referenced by layouts. Can be compared to how layouts and partials interacted in the legacy portal.
-
theme.conf.yaml
- This config file sets color and font defaults available to templates for reference as CSS variables. It also determines what options are available in the Kong Manager Appearance page.
Theme Assets
Path
-
format:
theme/*/assets/**/*
Description
The asset folder contains CSS/JS/fonts/images for your templates to reference.
To access asset files from your templates, keep in mind that Kong assumes a path from the root of your selected theme.
Asset Path | HREF Element |
---|---|
themes/light-theme/assets/images/image1.jpeg |
<img src="assets/images/image1"> |
themes/light-theme/assets/js/my-script.js |
<script src="assets/js/my-script.js"></script> |
themes/light-theme/assets/styles/my-styles.css |
<link href="assets/styles/normalize.min.css" rel="stylesheet" /> |
Note: Image files uploaded to the
theme/*/assets/
directory should either be a SVG, text string, orbase64
encoded,base64
images will be decoded when served.
Theme Layouts
Path
-
format:
theme/*/layouts/**/*
-
file extensions:
.html
Description
Layouts act as the HTML skeleton of the page you want to render. Each file within the layouts directory must have an html
filetype. They can exist as vanilla html
, or can reference partials and parent layouts via the portals templating syntax. Layouts also have access to the headmatter
and body
attributes set in content
.
The example below shows what a typical layout could look like.
<div class="homepage">
{(partials/header.html)} <- syntax for calling a partial within a template
<div class="page">
<div class="row">
<h1>{{page.title}}</h1> <- 'title' retrieved from page headmatter
</div>
<div class="row">
<p>{{page.body}}</p> <- 'body' retrieved from page body
</div>
</div>
{(partials/footer.html)}
</div>
To learn more about the templating syntax used in this example, check out our templating guide.
Theme Partials
Path
-
format:
theme/*/partials/**/*
-
file extensions:
.html
Description
Partials are very similar to layouts: they share the same syntax, can call other partials within themselves, and have access to the same data/helpers at time of render. The thing that differentiates partials from layouts it that layouts call on partials to build the page, but partials cannot call on layouts.
The example below shows the header.html
partial referenced from the example above:
<header>
<div class="row">
<div class="column">
<img src="{{page.logo}}"> <- can access the same page data the parent layout
</div>
<div class="column">
{(partials/header_nav.html)} <- partials can call other partials
</div>
</div>
</header>
Theme Configuration File
Path
-
format:
theme/*/theme.conf.yaml
-
file extensions:
.yaml
Description
The Theme Configuration File determines color/font/image values a theme makes available for templates/CSS at the time of render. It is required in the root of every theme. There can only be one Theme Configuration File, it must be named theme.conf.yaml
, and it must be a direct child of the themes root directory.