Paligo: How to Create Subsections

Headings, Sub-headings, and Chunking

If you're new to Paligo, you might be wondering how to add sub-headings to your topics. In this article, I'll show you the various ways of creating sub-headings in your output and explain the pros and cons of each.Let's start by making it crystal clear what sort of page structure I'm talking about. What we want to achieve is a page in the output that contains a main heading and some text, followed by sub-headings with text, like this:

So the area I've marked in yellow is what we need to create.This is going to be quite a long post as I'm going to try and share everything I have learned about sub-sections. You can use the links below to navigate to the various parts:

Bridghead for Sub-Sections

It is difficult to recommend using the <bridgehead> element. Yes, it allows you to have a sub-heading and heading in the same topic, but it is less useful than the <section> element.Really, you should only use the <bridgehead> element if:

You know that your sub-section will always need to be used with the rest of the topic
You need a heading that breaks the hierarchy of headings, for example, you need a <h4> between a <h2> and a <h3>.

In Paligo, create a new topic (click on a Folder's menu and choose Create Content > Topic). Give the document a Title. This will be the main heading for the topic, for example, 'Set the Clock'.
Edit the topic and add the text for each section.
Find the text that will be the sub-heading.
Click in the space between the sub-heading text and the next paragraph.

Press Enter to display the pop-up elements selector, and choose the bridgehead element.
Click in the bridgehead element (it shows 'Title' by default) and type in the text for your sub-heading.

Delete the element above the element (the element that contains the sub-heading text that you no longer need as you have the bridgehead element instead).
If you need the sub-heading level to break the hierarchy of headings, select the element. Then use the Element Attributes section to set its renderas attribute to the heading level you need (sect2 for H2, sect3 for H3, etc.)

Save your topic.

That's all there is to it. You now have a topic with its main heading (Title) and a sub-heading (bridgehead).Bridgehead Pros and Cons

It allows you to add a heading and sub-heading to the same topic. This can be easier for authors to manage the content, especially if a sub-section is unlikely to be reused.It can be set to any level, so does not have to follow the hierarchy of heading levels.

Limits content-reuse. The and the rest of the sub-section are tied to the topic that contains them. To reuse the sub-section as a whole, you would have to turn the sub-section into a reusable component.Cannot be controlled via the toc level or chunking options.Is not a hierarchical heading, and so has no structural relationship with other headings or content. This limits the way it can be processed for your output.

Separate Sections in the Same Topic

Every topic in Paligo is a section (it uses the <section> element). But you can create sub-sections inside a 'main' section too. The recommended way to do this is to use the <section> element. This will keep your sub-section in the same topic as the main section and also follows the hierarchical structure of the headings (unlike the bridgehead element). And if you discover you do want to reuse the sub-section at a later date, you can always turn it into an informal topic.

In Paligo, create a new topic (click on a Folder's menu and choose Create Content > Topic). Give the document a Title. This will be the main heading for the topic, for example, 'Set the Clock'.
Click after the para element ('Insert text') to select the end of the section element. You should see section selected in the breadcrumb. It is important that you select the closing section element, as you cannot add a new section inside an existing section.

Press Enter to display the element selector.
Choose section. Paligo adds a new section to your topic. It is shown as a box and has a section title element and paragraph element, ready for you to enter your sub-section content.

Use the same technique to add any other sub-sections.Note: If you want to add a sub-section within a sub-section, click on the closing section element of the sub-section, then add a new section element.
When you have all of the sub-sections you need, enter your content and save.

Using sections for sub-sections creates a similar structure (in the code) to using separate topics for sub-sections. Each section of your content is enclosed in its own <section> element.Section Pros and Cons

It allows you to add a heading and sub-heading to the same topic. This can be easier for authors to manage the content, especially if a sub-section is unlikely to be reused.Follows the heading hierarchy levels, so will use the appropriate heading style in the publication's table of contents.

Limits content-reuse, but not as much as the bridgehead element does. A sub-section can quickly be turned into reusable content, and as it has a title element, structurally, it is already the same as a separate topic.

Separate Topics for Sub-Sections

If you have a sub-section that might need to be re-used, you should consider creating separate topics. This can seem strange at first, especially if you are used to creating content in Word, or even some other topic-based systems, like Flare. But it does offer the most flexibility when it comes to content reuse.The idea is simple. Instead of having your main section and sub-sections in the same topic, you separate them into their own topics. Then you organise them into the hierarchy you want in the Publication's table of contents. In the image below, the three sections would all be created as unique topics.

Create each section that you need as a separate topic. For example, to create the page shown above, you would create a Set the Clock topic, a Set the Time topic, and a Set the Date topic. Don't worry about the heading levels, just give each topic a title.
Create a Publication (click on a Folder's menu and choose Create Content > Publication).
In the Content Manager, click on the Publication to display the Publication's settings, including its Structure.

Drag and drop your topics from the Content Manager into the Structure. When a topic is in the structure, you can drag it left or right to move it up or down in the hierarchy. For the page shown at the start of this section, you would create a structure like this:

Save the Publication.
Publish the Publication as HTML5.

By default, this will produce a HTML5 output that has a single page that contains the main section (in the example, 'Set the Clock') and the sub-sections ('Set the Time' and 'Set the Date').There are various options for controlling how the hierarchy levels are used in the HTML5 output. You can find most of them on the Layout editor, which I'll cover next.Section and Chunking Pros and Cons

The best option for content reuse.Sub-sections can be reused independently of main sections as they are independent topics.Follows the heading hierarchy levels, so will use the appropriate heading style in the publication's table of contents.

Your sub-sections are not in the same topic as the main section. This can make it more difficult for authors to manage, especially if they are not used to topic-based writing.

Taming the TOC

When you have sub-sections, you'll need to consider how they are going to appear in the table of contents menu in your HTML5 output. Paligo has several options for managing their appearance, and most of them are on the Layout editor.

Let's look at the options that affect the table of contents menu. First up, is the TOC section depth.

TOC Section Depth

The TOC Section Depth setting is pretty self-explanatory. It controls the level of sub-headings that are shown in the table of contents menu in your HTML5 output. The default setting is 3, which means once the table of contents menu is 3 levels deep, any deeper levels will not be shown. The 'deeper' topics will appear in searches, but cannot be accessed from the menu.

Only Include Chunks in TOC

This option is useful if you have a hierarchy of topics, and some of them contain sub-sections. It allows you to stop the sub-sections from appearing in the table of contents.For example, let's say you have a Publication structure like this:

This would produce a 2-level table of contents in the output like this:

Now, let's say that the 'Set the Time' topic also contains a sub-section called 'Set the Time Adjustments'. Should the sub-section be included in the table of contents as a menu option or should it be excluded because it is a section inside a topic, rather than a topic in its own right? By default, sub-sections within topics are included in the table of contents (note that this refers to 'proper' sub-sections and not bridgeheads).

To prevent sub-sections in Topics being shown as options in the toc menu, enable the Only include chunks in TOC option.

Chunk Section Depth

Use the Chunk Section Depth to control the level at which chunking occurs. Chunking means that once the structure reaches a certain level, any deeper topics will be added to the end of a parent topic.For example, let's say you have a five-level structure and the TOC level is set to 3. This means that your level 4 and 5 topics will not be in the table of contents menu, but will be on seperate pages. That can make it difficult for your readers to find the content, so one option is to set the Chunk Section Depth to 3. This causes the level 4 and level 5 sections to be added to the end of their parent topic (which is a level 3).

Legacy Section Chunking

In DocBook XML, there is no distinction between a section as a topic and a section as a sub-section, and so every section becomes its own web page. Paligo uses a customisation of DocBook that works differently - Paligo can tell the difference between a topic and a sub-section inside a topic.

The Legacy Section Chunking setting allows you to apply bog-standard DocBook to your content, so that every section is treated as a topic. Typically, you would only enable it if you had an old DocBook project that you were using in Paligo.

Okay, so those are the Layout options that affect the TOC structure. But there is one more thing to look at - applying chunk controls on a per topic basis.

Chunking on a Per Section Basis

You can use the Layout options to apply general toc depth and chunking rules. But you can also control chunking for each individual section element too. This is useful if you have some sections that need to be handled slightly differently to the rest. (You know, those *special cases* that cause us authors so many problems).

To make a section appear as its own web page (a chunk):

Edit the topic that contains the section element that is to be chunked.
Click on the section element and look in the Element Attributes.

In the Add attribute box, search for xinfo:chunk and add it to the Section's attributes. It is set to yes by default, so the section will chunk.

Note that the xinfo:chunk property takes precedence over the Layout settings.Right, I think that's everything I can tell you about sub-sections in Paligo. If you have any questions, please leave a comment.