Articles in this section

HTML and XHTML Styling

Avatar
Anders
  • Updated
Follow

If you are producing "clean" HTML or XHTML outputs, you can style and customize them in several ways:

HTML Layout Editor Options

The tree of items you can choose to style in the Layout Editor is divided into a number of sections. Each section is described below, with the items you can style and the options available for them.

Many of the items and options are self-explanatory and have explanations right in the Layout Editor. So only the items that may not be immediately transparent are explained below.

Note

The options here are only for the clean HTML/XHTML, not for HTML5. However, it also has options that apply when you choose to create a Zendesk layout. (Last section)

Tip

Learn how to set the footnote appearance for HTML, HTML5 and SCORM output, see Footnote Settings.

General (HTML)

Category

Description

CSS

Upload your own CSS to modify the default layout.

Make extra clean XHTML

The HTML output by default creates a clean valid XHTML. But it can be further cleaned by using this parameter to use e.g divs with classes instead of elements to denote emphasis, and similar.

Default: disabled (0).

Use inline style attributes

In some cases, the HTML output will include a style attribute, such as list style type on lists. If you want to exclude such attributes too, to only apply external CSS with classes, using no inline CSS, disable this option.

Default: enabled (1).

Create single page XHTML

Multipage: 0, single page: 1.

Default: multipage (0)

Create a title topic for reused publications

If you reuse publications within another publication, you can select whether that publication should be treated as a top-level topic, or if only it's child topics should be reused.

Only create topic for reused publications if no top-level topic

With this option enabled, you can mix reused publications where there is a top-level topic in some (in which case no title topic will be created for the publication), together with publications that have no top-level topic (in which case a title topic will be created for the publication).

Default: Disabled

Re-sort sorted tables automatically on publish

Even if you have sorted a table in the editor, re-sorting them on publish can be useful for example if you publish to multiple languages (in which case the sort order may be different), or if you have missed updating the sort before you publish.

Note

This will only affect tables that you have sorted with the sort commands in the editor first. 

Default: enabled.

Exclude label for abstract

If enabled, the label for an abstract is excluded from output. This is useful if you do not need it, and if publishing to multiple formats where hiding it with CSS does not work.

Default: disabled.

Classes and attributes (HTML)

Category

Description

Output taxonomies as class names

If enabled, you can get your taxonomy categories into your output as class names for further processing (e.g by css and javascript).

Value structure for taxonomy class names

You can set whether class names from taxonomies should output the value and all its descendant values in a taxonomy tree, just the value itself, or the value and its parent.

Default: Value and descendants

Underscore delimiter for taxonomy class names

When enabled, an underscore ('_') will be used to separate the parts of a taxonomy value output for class names in HTML5, instead of a dash ('-').

For most common purposes this is not necessary, but can be useful if you need to further process the separate parts of the value.

Default: disabled (dash is used)

Taxonomy filtering strategy

You can set whether taxonomies should be used for filtering, and whether to output the value and all its descendant values in a taxonomy tree, or just the value itself.

If you want to enable taxonomies for filtering, the most recommended value is to select "Descendants" to take advantage of the hierarchy of a taxonomy.

Default: Disabled

Output role attribute as class names

If enabled, you can get your role attributes into your output as class names for further processing (e.g by css and javascript).

Output profile/filtering attributes as class names

If enabled, you can get your profile/filtering attributes into your output as class names for further processing (e.g by css and javascript), such as creating "on-the-fly" filtering.

Use xml:lang as profiling attribute

If enabled, the language attribute xml:lang can be used for filtering on language (natural languages like Swedish, Japanese, etc)

Glossary popovers

When enabled, glossary terms will display the definition in a pop over in HTML5 Help Center output, when the user hovers over it.

Note: This currently has no effect on legacy HTML5.

Default: enabled for Help Center output.

Verbatim (code and software)

Category

Description

Use graphics for code callouts

If you'd prefer, you can use a graphic for the code callout, an svg image will then be used. Max 30 callouts with this option.

Use unicode symbol for code callouts

Another option is to use a unicode symbol for callouts. If this is set a symbol similar to the graphic and Font Awesome version will be used. Max 20 callouts with this option.

Note

If all of the above code callout options are disabled, a simple plain text output will be used for the callouts. By default a number within parentheses like this (1), but this can be modified in your CSS.

Use Font Awesome glyphs for code callouts

If you use calloutlist for annotating code samples, you can use Font Awesome for the "callout bugs". This is the default for HTML5.

Images (HTML)

Category

Description

Image Size

Set the resolution of the images in your published output. You can choose from:

  • Do not include images (removes all images from your output)

  • Use original images, which keeps the original resolution of the image file. Default

  • Fullsize (2500 x 2500px, 120 dpi)

  • Large (800 x 800px, 72dpi)

  • Medium (400 x 400px, 72dpi)

  • Small (400 x 400px,72dpi).

To find out more, see Adjust Image Resolution.

Zendesk

Category

Description

Fix cross links outside of publication scope

When publishing to Zendesk, Paligo will try to resolve even cross-references pointing to content that is not part of the current publication, so that you can publish to separate categories one at a time, but have links between them resolved.

Create article for the section topic

When publishing to Zendesk, Paligo will by default create a Zendesk article out of the content at the top-level topic, with the same title as the Zendesk 'section' created.

If you only use the top-level topic as a title for the section, you can disable this. Then only the section title will be created for that topic, and only the topics below it become articles.

Warning

  • If you disable this option, to not have an article created for the section, you cannot have a single article with no subtopics in your publication: each top-level topic must have at least one level of subtopics under it.

    Publishing with just a single topic will produce an error on publish.

  • If disabling the section article for existing content that you've published to Zendesk before (without this option disabled), please be aware that you need to keep the same topics ("forks") in your publication.

    I.e, you cannot rebuild the publication by dragging the same topics in again, you need to rearrange them in the same publication. Otherwise, the topics will get new ids, and new articles will be published instead of updating the existing ones.

    Some rearranging of articles may also be necessary after first re-publish.

    It is strongly recommended to test with a dummy publication with the default (enabled), and then re-publishing it with the option disabled, to see the effect.

Note

Disabling this will not remove previously published 'section' articles. 

Default: enabled

Use separate styling for label, number, and title in formal elements

If enabled, each part of the title for formal elements, like a table, example, or figure, will get a span element with a specific class name, so they can be styled differently or excluded, using CSS. Default: disabled.

Remove Header and Footer (HTML Output)

For HTML outputs (not HTML5), you have the option to suppress navigation. When enabled, this will remove the header and footer navigation from the HTML output. This feature is useful if you are embedding your Paligo content in a custom application that already has its own navigation features.

HTML output with callout arrows pointing to header at top and footer at the bottom.

Note

The HTML output header navigation is hidden by default via CSS:

.navheader {
    display:none;
}

To enable or disable the navigation suppression:

  1. Select Layout and then edit the layout that you are going to use for publishing.

    Alternatively, you can create a new HTML layout and edit that.

  2. Select Toc and chunking.

  3. Set Suppress navigation to:

    • Enable to turn on navigation suppression so that the navigation is not shown.

    • Disable to turn off navigation suppression so that the navigation is shown.

    The default is Disable.

    Note

    If you enable Suppress navigation, make sure that you provide a way for users to access the pages in your HTML output. You could use a custom application to provide the navigation or you can rely on the HTML output's table of contents.

    If you are going to rely on the table of contents, set the TOC section depth to a higher value than the Chunk section depth. This will mean that all chunked topics will appear in the table of contents, and so users can navigate to them. (Chunked topics are topics that appear on their own page in the HTML output).

    If the Chunk section depth is higher than the TOC section depth, there may be pages that are not shown in the table of contents, and so users cannot navigate to them.

  4. Check the box Use gateway to enable IP Allowlisting. Optional

When you publish to HTML using this layout, the output will include or exclude the header and footer navigation, based on the setting in the layout.

HTML Styling Workflow

To customize and style HTML outputs, use a CSS stylesheet. There are also some general settings in the HTML layout that affect the output as a whole.

We recommend that you follow these steps to style your HTML:

  1. Create your content in Paligo topics and add to a publication. Some parts of the content can be styled by using attributes, for example, you can set image sizes. But you will apply most of the styling in the HTML layout and in a CSS stylesheet.

  2. Create an HTML5 (or plain HTML) layout or edit an existing one.

  3. Use the layout settings to choose your publishing settings. These are "overall" settings that apply to the content as a whole. You do not set styles such as headings, font sizes, font colors etc., in the layout. For HTML, you define those in a CSS stylesheet that you can then upload to your layout.

  4. Use a code or text editor to create a CSS file. Give it a suitable name and save it with the .css extension.

  5. Give your CSS a simple rule to start with, so that the file is not empty. The rule does not have to contain any styling yet, for example, you could add:

    body {
}

  6. Upload your CSS file to the HTML layout.

    The CSS setting for uploading your CSS file is in the CSS, JS, logos and other assets section.

    CSS settings box with a single field. The field has an Upload button.

    Note

    You can also use javascript to customize your published output. You can upload your custom javascript to the HTML layout too.

  7. Check the box Use gateway to enable IP Allowlisting. Optional

  8. Publish any publication that contains a sample of the content that you want to style. When you publish, use the HTML layout that you edited in steps 2-7.

  9. When your content is published, unzip the zip file that is downloaded in your browser.

  10. Open the Index.html file to display your HTML output.

  11. In the unzipped files, go to the out/en/css folder, and find the custom CSS file that you uploaded to your layout. It is called "layout-custom-style.css" if you have enabled the Persistent CSS file name option for your layout. Otherwise, it has a random number ID as its name.

    Note

    en is the folder for English content. For other languages, there is a different language code.

  12. Open the CSS file in a text or code editor and add rules in the CSS. Then refresh your browser to see the effects on your help output.

    Tip

    Use the browser tools to inspect elements and test style changes directly in the browser, before you add styles to your CSS file. For tips on using the browser tools, see Style with CSS.

  13. When you are happy with your styling, upload your customized CSS file to your layout again. Paligo will apply your new styles the next time you publish.

Tip

For tips on styling a HTML5 help center, see HTML5 Help Center Styling.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk