Skip to main content

API Documentation

Paligo has an API-style output that is designed especially for developer documentation. It provides a modern, appealing API documentation output, that includes navigation, your content, and code examples that are tabbed by language in a sidebar on the right.


To use the API-style output, you need to markup your content with certain elements, such as programlisting and code. You also need to publish to HTML5 and use an HTML5 API Style layout.

Procedure. How to use the API style output

Programlisting elements and example elements on the top level (directly under the root section element) are automatically placed in the sidebar to the right, and synced to the text in the main body.


As code samples and example elements are placed next to each section, it works best when the examples are not too long, and with separate sections or topics for each main example.

  1. For code elements (programlisting, code, etc) there is the built-in DocBook attribute language. Use that to set what programming language the code is for.

  2. For any other elements, there is a specialized Paligo attribute called xinfo:proglang. You can use that on any element for filtering content, with the exception of table rows. You can also use it for switching example and informalexample elements in the sidebar.

  3. If you need to exclude a specific example from the sidebar, and show it inline in the body content, you can do so either by:

    1. Putting it anywhere but on the first level under section

    2. Adding the role attribute on an example or informalexample, and set it to "inline-example". For this to work, you also need to enable outputting role attribute as class names in your layout in the Layout Editor.

  4. If you have just one programming language in your examples, the code switcher navigation bar will automatically be hidden.

  5. Disable the code switcher if you want all language samples to display.

    Even if you have multiple languages in your examples, you may want to disable the code switcher and show all examples for all content.

    This could be the case for instance if you're documenting not an API with multiple versions for different languages, but developer or other software documentation where different programming languages are used for different features, and all should be shown. This can be done by setting the parameter "Use code switcher for API style output" to 0 (disabled) in the Layout Editor, under "Verbatim (code elements)".


If you do not have your own API content, but want to experiment with the API layout, you can use Swagger/Open API content from:

Put the Swagger/Open API content in a folder on your computer and then zip it. Then import the zip file into Paligo using the import Open API feature.

Alternatively, you can import this sample project that we have made:

You will need to Import the sample project as a Paligo export file.