Getting Started

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.

swagger-openapi-published-as-apioutput.jpg

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.

Tip

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, and it will also be used 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)".

Tip

Ask support if you want a pre-made API example to import into your Paligo account to experiment with the possibilities.