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:

Use the Publication Structure to Create Subsections

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 32. 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".

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.

Use Chunking to Control Subsections

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.

   Alternatively, you can Create a Topic and edit that.

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

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.

5. Select Save.

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

You are going to publish to HTML5 and your layout has Chunk section depth 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.

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.

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:

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

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

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:

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:

To set up SEO-friendly and reader-friendly URLs:

When you use the layout to publish your content, your chosen settings will be applied to the HTML output.

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.

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

// 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');
    }); */
});

One way to change the title of a topic without affecting its URL is to use the xinfo:outname attribute. This attribute is available for the section element.

When you set an xinfo:outname value, that value is used for the URL of the HTML page for that topic. The xinfo:outname takes priority over all other URL settings, so will be used even if you set the HTML layout to use topic names instead of titles.

To keep the existing URL of an HTML page:

When you publish to HTML, Paligo will use the xinfo:outname value for the page part of the URL. It will not use the title or the topic name, the xinfo:outname takes priority.

You can set Paligo to use topic names instead of titles for the filenames and URLs for HTML pages. The topic names are then used instead of the title text for the page part of the URLs.

For example, if a topic is named "IoT Controls" and has a title of "Controls for IoT System", the URL for the page in the HTML output will look like this: https://acmehelp/docs/en/iot-controls.html

To set Paligo to use topic names instead of title text for URLs:

If you enabled the Use resource name instead of title for the HTML output filename setting, Paligo will use the topic names for the filenames and URLs. This means you can now change your topic title text without affecting the URLs for the pages.