Getting Started with Paligo

About the Built-In HTML Templates

You can publish to a number of different HTML outputs in Paligo:

  • HTML5 Responsive Design: A very modern HTML output that adapts to any screen size, from desktop to mobile. Bootstrap is built-in allowing many possibilities for features.

    See more about the built-in variants below!

  • Clean XHTML: A very clean "plain vanilla" HTML of the structured XHTML type if you want something that you can model as you please.

  • Help desk HTML: This is the publishing of HTML adapted to help centers like Zendesk, Freshdesk, and (Salesforce) Desk.com.

    This publishing option is a direct integration to the help center, and as soon as you publish from within Paligo it is directly available on your support portal.

HTML5 variants

The built-in templates for HTML5 are ready-made layouts that will give you a modern design right out of the box. Of course each one can be modified by yourself by uploading your own CSS in an override layout that you create in the Layout Editor.

The templates represent a few different popular layout structures:

Multi-page HTML5

This is the modern HTML5 version of the popular "tri-pane" format for online help. Each page/help article is presented on its own (multi-page), and you navigate them in the Table of Contents (TOC).

Single-page HTML5 (Article style)

Another HTML5 variant that has become very popular is the long single-page article style. It is all one long page with a very clean design, and with navigation that follows along.

The Table of Contents is "sticky" and color bars indicate clearly where you are on the page.

API documentation style

For those that are documenting software with a lot of code or examples, there is a template we call the API style, as it is a type of style that has become especially popular for API documentation.

  • Code and other examples are automatically placed in the sidebar, and the examples are in sync with the body text.

  • The content is filtered "on the fly", meaning that you can select which programming language version you want to see examples for.

    If you click Ruby, all example code is in Ruby, if you click Javascript all sample code instantly switches to show Javascript, etc.

  • The main body content will also be filtered on the fly, based on filter attributes you use in your Paligo content. 

  • The theme can be easily customized, selecting a different code sample theme and syntax highlighting with a parameter, and some CSS to modify the rest.

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 synked 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.