Customizing the Kong Developer Portal
Introduction
The Dev Portal default theme is shipped with two CSS file partials:
partials/unauthenticated/theme-css.hbs
Default styles for all theme specific elements across the Example Dev Portal.
partials/unauthenticated/custom-css.hbs
Partial describing how to change specific parts of the portal without modifying the default theme CSS.
We strongly encourage you to use the custom-css
over modifying theme-css
for small changes so you don’t affect the original styles.
Working with Page Layouts
To avoid duplicating code in pages and partials, layout partials can be created and used on multiple pages that share common layout.
The Example Dev Portal includes one basic layout: partials/layout.hbs
Let’s create a new page using this template.
Creating a New Page
We’re going to create something super simple, a Hello World page using the layout
template described above:
- Create a new file with the name
example.hbs
in your Example Dev Portal files directory under thepages/
directory. -
In the file we just created, let’s add the following code (the handlebars syntax for opening a partial block):
Note: The
pageTitle
attribute allows you to easily change the title of the page displayed in the browser. Here we have set it toHello World
. -
Now let’s add the actual content. When using the layout template, content on the page must be placed inside an inline partial block named
content-block
like so: -
Now let’s close out the layout block:
-
Your file should now look like:
-
Add it to Kong specifying the file as a page:
curl -X POST http://127.0.0.1:8001/files \ -F "name=example" \ -F "type=page" \ -F "contents=@pages/example.hbs" \ -F "auth=true"
- To learn about the
auth
flag see the Adding Authentication section. - Note that the name must match that used in the handlebars file (example and example.hbs in this sample)
- To learn about the
…We’re done, this is how our page should look:
Add New Page to the Nav
Previously we created example.hbs
, let’s add it to the Developer Portal navigation so its accessible to everyone:
- Find and open
partials/header.hbs
in the Example Dev Portal file directory. -
Open it in your favorite text editor and find the
nav
container, it should look like: -
Let’s add the following line:
<li> <a href="/example">Example</a> </li>
-
Your
nav
block should now look like: -
Finally let’s update it using the Dev Portal File API:
curl -X PATCH http://127.0.0.1:8001/files/header \ -F "contents=@partials/header.hbs"
- Once uploaded, refresh your Dev Portal and you should see the change:
Link From One Dev Portal Page to Another
-
Add a link in the code of a page or partial like:
<a href="/example">Example</a>
- This will link to a Page with
name=example
-
To link to an anchor or section within
/example
, ensure the target includes an unique id:<div id="details">Details Here</div>
-
Your link should look like:
<a href="/example#details">Example</a>
-
Update the page you edited via the Dev Portal File API and reload that page - you should see the link you added, and when you click it, it will take you to the linked page, and, if you coded it, to the anchor.
Adding Image, Video, or other file types to a Page
The Dev Portal File API serves only Pages, Partials, and Specifications. To add images, videos, and other file types to your pages, you must either add them inline (e.g. inline SVG) or link to the files being served by some other web server.