Customizing the Kong Developer Portal
Introduction
Now that you have the Example Dev Portal running and you understand how files interact with and are served by the Dev Portal Loader, lets go through the steps of customizing the look and feel of the Example Dev Portal.
In order to customize the Example Dev Portal, you generally follow these steps:
- Issue a
GET
command to:8001/files
to see a list of all your Dev Portal Files. - Take the
contents
of the file(s) you would like to modify and edit them to your liking in a local editor.
Alternatively, you can create new files usingPOST
requests if you do not wish to modify existing files. PATCH
the files back into Kong using the:8001/files/<filename>
endpoint.- Reload the Dev Portal in your browser - you’ll see the results of the changes you made.
Going forward, we will be modifying and updating the files from the Example Dev Portal file archive.
Uploading your Specification file
- Find your Specification file in your filesystem, it should be either a Swagger
json
oryaml
file.- Should you not have one, we can use the Swagger Pet Store Example: Download File
-
Upload the Specification with the following curl request in your terminal (relative to the file):
curl -X POST http://127.0.0.1:8001/files \ -F "type=spec" \ -F "name=swagger" \ -F "contents=@swagger.json"
Note: The
@
symbol in thecurl
command will automatically read the file on disk and place its contents into thecontents
argument.
Now let’s update pages/documentation/api1.hbs to render our newly added Specification file:
- Find the
pages/documentation/api1.hbs
file in your Example Dev Portal Archive -
Find the following line of code:
- Change:
petstore
→swagger
-
Now make a
PATCH
request to update the page against the Dev Portal File API in your terminal (note, no extension on the filename in the url):curl -X PATCH http://127.0.0.1:8001/files/documentation/api1 \ -F "contents=@pages/documentation/api1.hbs"
- Lastly, navigate to
:8003/documentation/api1
in your browser, you should see that the specification has changed and should look like the following (assuming you used the petstore swagger file from above):
Customizing the look and feel of your Dev Portal
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 and get unwanted collateral damages.
For this example, this is what we’re going to do:
Structure
- Find and open the
partials/header.hbs
file from the Example Dev Files archive you downloaded earlier. -
Change the content inside of the
.logo
element toDev Portal
<a class="logo" href="/">Dev Portal</a>
-
Change
Developers
→My Company Developers
:<span>My Company Developers</span>
-
Update the file by sending a
PATCH
request from your terminal to the Dev Portal File API:curl -X PATCH http://127.0.0.1:8001/files/header \ -F "contents=@partials/header.hbs"
- Refresh the Example Dev Portal. You should see something similar to below (don’t worry, we are going to make it look better after we change the styles):
Style
- Find and open
partials/unauthenticated/custom-css.hbs
in the Example Dev Files directory. -
Let’s start by changing the header background, and text colors by adding:
#header { background-color: #033151; color: #FFFFFF; }
-
Next, we’re going to change the font color in the navigation from blue to white by adding:
.navigation > li > a, #headerSpecDropdownWrapper > .header-text { color: hsla(255, 100%, 100%, .45) !important; }
-
Almost there, now let’s change the logo text to white, increase its size, and update the separator color:
#header .header-logo-container .logo { color: white; font-size: 20px; font-weight: 700; border-right-color: hsla(255, 100%, 100%, .45); }
-
Save the file and send a
PATCH
request in your terminal to the Dev Portal File API to update it:curl -X PATCH http://127.0.0.1:8001/files/custom-css \ -F "contents=@partials/custom-css.hbs"
- Refresh the Example Dev Portal in your browser and now it should look like this:
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.