Skip to main content

Subsections

To make a text easier for the reader to consume, you can use subsections to divide your content into smaller pieces of information, see Create Subsections.

Benefits of using subsections:

  • Readers can quickly scan the main title and the subtitles to get a feel for what the page is about.

  • Subsections make the writer focus on the information needed for the subsection rather than the topic as a whole.

  • Smaller sections of content are more visually appealing. A long page of text can be off-putting.

Image of Topic Templates page from the Paligo help. It has a main heading "Topic Templates" followed by some text and then a subheading "Create a Topic Template", which is followed by text and an image.

This example shows the "Topic Templates" page that contains a subsection called "Create a Topic Template".

Subsections is a great way to make your content easier to read, as you can use them to break up a page into separate, but related pieces of information. There are several ways to create subsections in Paligo, each with their own pros and cons. If you know that you will need to reuse your main sections and subsections separately, you can create each section as a separate topic and then:

But the downside of this is that when you are editing, you can only see one section at a time. (In the output, your readers will see the content as a main section with a subsection on the same page, if space allows). If you want to be able to see the main section and the subsection in the same topic while editing, use of these methods:

Note

With these two methods, the subsections are shown inside the "main" topic. But this also means that if you reuse the "main" topic, you will also reuse the sections inside it.

A topic called "Main Topic" shown in Paligo's editor. It contains several subsection topics, "Subsection A", "Subsection B" and so on.

You can use the publication structure to create subsections. When you publish, Paligo will automatically create the same structure in the output.

Watch the video or see the text below,

 
  1. Create all of your sections and subsections as separate topics. For example, if you have an Introduction topic and you want it to contain a References subsection, create one topic for Introduction and one topic for References.

  2. Open the publication structure.

  3. Drag your topics into the structure. You can create subsections by dragging the topics left and right below other topics.

  4. For HTML outputs only, select Layouts and edit the layout you will use for publishing. In the Toc and chunking settings, use Chunk section depth to control whether topics become subsections. The default setting is 3, which means any topics at level 4 or below in the publication structure will become subsections of the level 3 topics.

    Note

    If a topic is set to have xinfo:chunk=yes, it will always be on its own page, even if it is at a lower level than the Chunk section depth. (see Use Chunking to Control Subsections)

  5. Publish your content.

For PDF outputs, the subsections are shown on the same page as the main section, where space allows. They are set as subsections with lower heading levels automatically.

For HTML outputs, Paligo displays each topic on its own page until the Chunk section depth is reached. Topics at a lower level then become subsections, unless they are specifically set to be separate chunks (see Use Chunking to Control Subsections).

Example 1. Subsections in a PDF Output

In this example, we have three topics. To keep the explanation simple, we have named them "Heading 1", "Heading 2" and "Heading 3".

In the publication structure, "Heading 1" is set as the top-level topic and "Heading 2" and "Heading 3" are nested as subsections below "Heading 1".

headingsstructureview.png

We publish to PDF.

Paligo detects the hierarchy of topics in the publication and recreates it in the PDF output. The "Heading 2" and "Heading 3" topics appear as subsections of the "Heading 1" topic.

headings.png

You can use Paligo's chunking feature to control whether a topic can be used as a subsection or to appear as a separate web page in the HTML / HTML5 output. The term "chunk" means that a topic has to be on its own. So if a topic is set to xinfo:chunk with the value set to:

  • Yes - the topic cannot be a subsection inside another topic and will always be on a separate page when published. It cannot be a subsection on another page.

  • No - the topic can be a subsection inside another topic.

Note

Learn more about chunking settings, see Chunking.

To set the chunking value:

  1. Select the topic or component in the Content Manager to open it in the Editor.

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Select the section element in the Element Structure Menu.

    Close up of Element Structure Menu. It shows the section element is selected and the Go to element option is selected.
  3. Select Go to element.

  4. Add the xinfo:chunk attribute in the Element Attributes Panel and set its value to:

    • Yes to prevent the topic from being a subsection.

    • No to allow the topic to be a subsection.

    Element attributes side panel. It shows the section element has an xinfo:chunk attribute that is set to yes.
  5. Select Save. Save icon.

Important

The xinfo:chunk value takes priority over the Chunk section depth setting in the layout editor. For example, if you set the Chunk section depth to 3, it normally means that any topics at level 4 or below will become subsections of the "parent" level 3 topic. However, if your level 4 topic has xinfo:chunk = yes, the level 4 topic will not be included as a subsection of its "parent" level 3 topic. Instead, it will be a separate topic.

There are two ways to use chunking (and they can be combined):

  • Set the default level at which you want topics to become a chunk under "TOC and chunking" in the Layout Editor.

  • Add the xinfo:chunk attribute to the section element in a topic via the Element Attributes Panel.

Example 2. Chunk section depth and xinfo:chunk used in combination

If you have a publication called "Mars Travel Manual" and you have organized it so that there are topics at different levels.

Image shows structure view of Mars Travel Manual publication. There are topics in the publication and some are at the top-level, some are at the second level, and some are at the third level.

You are going to publish to HTML5 and your layout has Chunk section depth set to 2.

HTML5 layout with the Chunk section depth option set to 2.

When you publish, the output has the top-level and second-level topics as separate pages. The third-level pages and lower are subsections.

A publication structure with 3 tiers. At the top is a topic called "The Mission Control Center" and is it labelled as 1. At the next level down is a topic called "Command Center" and it is labelled as 2. At the next level down are two more topics and these are labelled as 3.

So if we look at the "The Mission Control Center" topic and its lower-level topics, the output will work like this:

  1. "The Mission Control Center" is a top-level topic. It is higher than the Chunk section depth setting of 2, so it has its own page in the output.

  2. "Command Center" is a second-level topic. It is at the same level as the Chunk section depth setting of 2, so it has its own page in the output.

  3. "Controls System" and "Control Room" are third-level topics. They are below the Chunk section depth setting of 2, and so they do not get their own page. Instead, they are subsections on the "Command Center" topic, as that is their immediate "parent" in the publication structure.

Note

The green dotted line in the image represents the Chunk section depth setting of 2.

But what if you wanted "Controls System" to be a subsection of "Command Center" and "Control Room" to have its own page? To do that, you would set the "Control Room" topic to have the attribute:

xinfo:chunk = yes

With this in place, Paligo will give the "Controls System" topic its own page in the published output, as xinfo:chunk takes priority over the Chunk section depth setting. So the result is that the output has:

  • "The Mission Control Center" and "Command Center" topics have their own pages as they are at a higher level than the Chunk section depth.

  • "Control Room" has its own page as it has xinfo:chunk=yes. The Chunk section depth does not apply to this topic.

  • "Controls System" is a subsection of "Command Center" as it does not have xinfo:chunk=yes and so the Chunk section depth does apply.


If you like to be able to see the subsections inside topics while editing, using components for subsections is a good choice. With this technique, you create your main section and subsections as separate topics, and then import the subsections into the main topic. You can then view the main topic and subsections all inside the same topic. This can make it easier to check the flow of your content and that you have covered all of the points you need to make.

To learn how to use components for subsections, watch the video or read the instructions below.

 
  1. Create all of your sections and subsections as separate topics. For example, if you have an Introduction topic and you want it to contain a References subsection, create one topic for Introduction and one topic for References.

  2. Open a topic that will be a main section that contains subsections.

  3. Select the Insert tab in the Toolbar.

    Toolbar_Insert_small.png
  4. Select Component and choose a topic. Insert_Component.png

    insert-topic-component.jpg

    The topic is added as an import element and you can see it as a subsection in your topic.

  5. Repeat steps 3 to 4 for each of the subsections you want to add and save each topic.

  6. Select Save. Save icon.

  7. When you have finished adding topics as components, publish to HTML.

A quick and easy way to create a subsection is to add a section element inside another section element. You will then be able to see the main section and the subsection in the same topic while you are editing. However, there are some limitations with this technique that makes it better to use an inserted component instead:

  • Reusability - You cannot reuse the subsection in other topics, unless you Convert Subsections into Separate Topics and import them as components, see Use Components to Create Subsections.

  • Number of subsections - The Paligo validation recommends a limit of10 sections per topic (a main section with 9 subsections) and enforces this via the "Paligo Recommended Rules" in the Editor Settings when validating / saving a topic. Note that there is no limitation when it comes to subsections that are inserted as components. However, if you know that a subsection is only needed in one topic, you can create it as a section inside a section. Read about possible settings in Editor Settings.

  • Searchability - Subsections not being inserted as components can be more difficult to find in the web search than topics. They can also be harder for the writer to via the Content Manager.

To add a second section element as a subsection:

  1. Position the cursor at a valid position for a subsection.

    You can only insert a section for a subsection at a position that is both:

    • A direct descendant of a section element (either the section for the main topic or a section for a subsection). It cannot be inside another element.

    • Immediately followed by another section element or a closing section element (</section>).

      You cannot have content "floating" between subsections or between a subsection and the end of the main topic. Your content must be inside the main topic and before the subsections or inside one of the subsections.

    correct-position-for-insert-section.png

    CORRECT: The cursor is positioned outside the other elements, and is a direct descendant of the section element of the main topic. The element that follows the position is the closing element for the main topic, and so is </section>. A subsection can only be followed by a section or closing section element.

    incorrect-position-for-insert-section.png

    INCORRECT: The cursor is positioned inside an element. The selected position is not a direct descendant of the section element of the main topic.

    Note

    In a topic, all of the content, including your subsection section elements, must be inside the main <section> and </section> tags of the topic.

  2. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.
  3. Enter section and select it from the menu.

    A new section element is added to the topic. As it is inside the main section element, the new section appears as a subsection.

  4. Enter the title for the new subsection. You can then add content to the subsection in the same way as any other topic.

Note

You cannot add para elements and other block elements between subsections. The only valid content after the end of a subsection is another subsection.

Long topics with many subsections can be difficult to read because there's too much information provided in one place.

To avoid this "cognitive overload", you can convert the subsections into separate topics. You can choose to:

A topic called "Main Topic" shown in Paligo's editor. It contains several subsection topics, "Subsection A", "Subsection B" and so on.

In the image above, the subsections have been converted into separate topics and they are embedded in the main topic.

Tip

If you need a topic to contain several subsections, you can make the content less overwhelming by using Accordions (Collapsible Sections). They allow a subsection to be collapsed, which makes the subsection content only visible when the reader selects the subsection heading.

To convert a topic's subsections into separate topics, you can use Paligo's Convert reusable component feature.

  1. Select the title of the subsection you want to convert in the Element Structure Menu.

    select-section-for-subtopic.jpg
  2. Select the section element for the subsection.

    Note

    Make sure that you select the subsection's section element and not the main section element for the topic.

  3. Select the Convert reusable component from the menu.

  4. The existing subsection title is suggested as topic name. You can edit it if necessary.

    convert-to-reusable-component.jpg
  5. Select the folder to store the topic in.

  6. Select the Reuse the component at position checkbox (in the lower left corner) to embed it in the current topic as a subsection.

    If not selected the new topic is removed from the parent topic.

  7. Select OK.

    Paligo converts the subsection into a topic. If you checked the Reuse the component at position checkbox, the new topic is embedded in place of the subsection otherwise the subsection is removed from the topic.

Note

Reader-friendly URLs for subsections is only supported by HTML5 help centers.

With Paligo's Reader-friendly fragment identifiers (hash links) feature, you can have subsections that use a text URL instead of a unique ID (UUID). The text URLs are easier for people to understand, and so are better for when you need to share links to your HTML pages.

For example, if the UUID is used for creating the URL of a subsection, you get a URL like this:

The URL of a link to a subsection on a page. The subsection part of the URL has a hash tag followed by the UUID, which is the unique ID of the subsection.

Where the link targets the subsection by using the hashtag (#) followed by the UUID of the subsection's section element.

But if you enable the Reader-friendly fragment identifiers feature, the URL will use the text of the title element instead of the UUID, like this:

URL of a link to a subsection on a page. The subsection part of the URL has a hash tag followed by the title of the subsection.

Note

URLs for subsections are also known as "hash links", as there is a hashtag # in the structure of the URL.

Accordions are sections of content that can be expanded or collapsed for HTML5 or Zendesk output. They are useful when you have a lot of subsections that make it hard to overview the topic. The reader can then expand or collapse each section in turn.

You can use accordions on sidebar elements and section elements. But for sections, the accordion only appears when that topic is inserted into another topic as a subsection, see Insert Component.

Paligo Accordion (Collapsible Sections)

Paligo supports accordions (collapsible sections) for HTML5 and Zendesk output. In other output formats, the content will appear as regular text. You can create accordions for topics (section elements) and informal topics (sidebar elements).

There are two ways to create an accordion. Use the way that matches what you want to achieve:

When you have created an accordion, use Preview to test that it works (see Test your Accordions.)

Set an Accordion on a Section Element

If you want a topic to use an accordion wherever that topic appears, give the topic's section element a role attribute with value set to accordion:

  1. In the Content Manager, find the topic (or informal topic) and select it to open it in the editor.

  2. In the Element Structure Menu, select a section element or sidebar element and then select Go to element.

    section-gotosection.png

    Note

    It is possible to have multiple section elements in a topic. The first (leftmost) section represents the topic as a whole. Any other section elements are for subsections inside the topic. We recommend that you create subsections by inserting a topic as a component inside another topic rather than create a section inside a section.

  3. Select Add attribute in the Element Attributes Panel.

    select-add-attribute.png
  4. Enter Role and select it from the menu.

    add-role-to-section.png
  5. Enter accordion as the role attribute value.

    set-role-accordion.png
  6. Select Save. Save icon.

  7. Select Layout and then select the Layout you are going to use for publishing. Make sure that the Output role attribute as class names setting is enabled (for details, see Enable Output Role Attribute as Class Names). Accordions will not work if this setting is disabled.

When you publish to HTML5 or Zendesk, the section or sidebar will appear as an accordion (when it is a subsection of another topic).

Tip

You can style the accordion by using custom CSS.

For example, if you want a background color for the header, create a CSS file (or edit an existing one) and use:

.panel-default > .panel-heading { background-color: #fafafa; padding: 1em; }
        

You can then upload the CSS to your Layout (see Upload Customized CSS).

Set an Accordion on an Imported Subsection Topic

If you create subsections by inserting a topic inside another topic, you can set the subsections to display as an accordion. There are two ways to do this:

  • Set the subsection topic to have role:accordion on its section element. This makes the topic display as an accordion wherever it is used (see Set an Accordion on a Section Element).

  • Edit the source code for the container topic ("parent" topic) and set the xi:include element for the subsection to have xlink:role="accordion". This makes the subsection topic display as an accordion, but only when it is used as a subsection in this particular "parent" topic. If the subsection topic is also used elsewhere, it will not display as an accordion in those other locations (unless you set it up to have an accordion in those places too).

To edit the source code for the "parent" topic and make an imported subsection display as an accordion:

  1. In the Content Manager, find the "parent" topic that contains the subsection ("child" topic). Select the "parent" topic to open it in the editor.

  2. Click on the subsection ("child" topic) and then look in the Element Structure Menu at the top. Make sure that the subsection is represented by an import element in the structure of the topic.

    A "parent" topic that contains another topic as a subsection. A callout box highlights the import element in the Element Structure Menu. Another callout box highlights the subsection "child" topic.

    A topic containing another topic as a subsection. The subsection topic has been inserted as a component and is referenced by an import element.

    If you do not see an import element, it is likely that the subsection has been created in another way. For example, added as a section element inside the "parent" topic. You can convert it into an inserted component by selecting its section element and then choosing Convert to reusable component. Paligo will convert the section into a separate topic and add an import element in its place.

  3. Select the Edit tab in the toolbar.

    Toolbar_Edit_small.png
  4. Select Edit source code. Edit_Source_Code_small.png

  5. In the Source Code Editor, find the reference to the subsection topic ("child"). It is shown as an xi:include element and it contains an xi:fallback element with a para element inside it, like this:

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="UUID-17301a40-98ec-d396-2c42-1880b82e5358">
        <xi:fallback>
          <para xinfo:translate="no">Reusing topic #UUID-17301a40-98ec-d396-2c42-1880b82e5358</para>
        </xi:fallback>
      </xi:include>

    Note

    If your "parent" topic contains many imported subsections, it will have an xi:include element for each one. They are shown in the order they appear in the "parent" topic. Make sure that you are looking at the xi:include for the subsection you want to edit.

  6. Add xlink:role="accordion" to the xi:include element. It should come after the href attribute and value. For example:

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="UUID-17301a40-98ec-d396-2c42-1880b82e5358" xlink:role="accordion">
        <xi:fallback>
          <para xinfo:translate="no">Reusing topic #UUID-17301a40-98ec-d396-2c42-1880b82e5358</para>
        </xi:fallback>
      </xi:include>
  7. Select Update.

    If the source code is valid, Paligo saves it and closes the Source Code Editor. If the code is invalid, Paligo displays a notification. Check the code carefully for any errors and correct them.

  8. Select Save. Save icon.

When you publish your content, or preview it as HTML5, the subsection will display as an accordion. If you use the subsection topic elsewhere, it will not display as an accordion*.

*unless those other locations are also configured to have xlink:role="accordion".

Test your Accordions

When you set up a new accordion, it is a good idea to test it works as expected before you publish. You may find that you have made a mistake and the accordion is not working or that you have included information in the accordion that needs to be elsewhere.

To test an accordion:

  1. In the Content Manager, select the "parent" topic that contains the subsection topic that has the accordion. Paligo opens the topic in the editor.

  2. Select Preview and then HTML5.

    Paligo editor toolbar. The Preview tab is selected and highlighted. The HTML5 option on the Preview tab is highlighted too.

    Paligo opens a preview in an new tab.

  3. Select HTML5.

  4. If you have set up the accordion correctly, the subsection topic is displayed as an accordion. You can only see its title and there is an arrow icon next to it.

    A topic displayed in a preview. It has its main heading shown, a paragraph of text, and then the heading for a subsection. There is an arrow next to the subsection heading. The content of the subsection is hidden.

    If you select the subsection topic's title or the arrow icon, it should expand the accordion, revealing the content in the topic.

    A topic displayed in a preview. It has its main heading shown, a paragraph of text, and then the heading for a subsection. There is an arrow next to the subsection heading. The content of the subsection is displayed as the accordion is expanded.

    If the accordion is not working as expected, check that you have set up the accordion correctly (see Set an Accordion on a Section Element or Set an Accordion on an Imported Subsection Topic). Look out for typing mistakes in the role attribute values and make sure you have applied the role to the correct element.

If you want all accordions to expand when a page in the HTML5 Helper Center output is loaded, add the following code to your custom JavaScript:

// Expand accordions
$(document).ready(function () {
    $('.accordion .collapse').collapse('show');
    $('.accordion .panel-heading').addClass('active');

    // Uncomment below if you're using AJAX
    /* $(document).ajaxComplete(function() {
            $('.accordion .collapse').collapse('show');
            $('.accordion .panel-heading').addClass('active');
    }); */
});

Note

This script will apply to accordions on any page and will only work for HTML5 Helper Center output.