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.
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.
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,
-
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.
-
Open the publication structure.
-
Drag your topics into the structure. You can create subsections by dragging the topics left and right below other topics.
-
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) -
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).
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.
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:
-
Select the topic or component in the Content Manager to open it in the Editor.
-
Select the
section
element in the Element Structure Menu. -
Select Go to element.
-
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.
-
-
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 thesection
element in a topic via the Element Attributes Panel.
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:
-
"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.
-
"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.
-
"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.
-
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.
-
Open a topic that will be a main section that contains subsections.
-
Select the Insert tab in the Toolbar.
-
Select Component and choose a topic.
-
Repeat steps 3 to 4 for each of the subsections you want to add and save each topic.
-
Select Save.
-
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:
-
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.
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.
-
-
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
-
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 newsection
appears as a subsection. -
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:
-
Create subsections by embedding a topic inside another topic, see Insert Component.
-
Keep the topics separated and use Cross-References and Links to guide people from one topic to another.
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.
-
Select the
title
of the subsection you want to convert in the Element Structure Menu. -
Select the
section
element for the subsection.Note
Make sure that you select the subsection's
section
element and not the mainsection
element for the topic. -
Select the Convert reusable component from the menu.
-
The existing subsection
title
is suggested as topic name. You can edit it if necessary. -
Select the folder to store the topic in.
-
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.
-
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:
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:
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 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:
-
Set a a topic to display as an accordion, but only when it is included inside another specific topic as an imported component.
If you are unfamiliar with inserting topics as components, see Insert Component.
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:
-
In the Content Manager, find the topic (or informal topic) and select it to open it in the editor.
-
In the Element Structure Menu, select a
section
element orsidebar
element and then select Go to element.Note
It is possible to have multiple
section
elements in a topic. The first (leftmost)section
represents the topic as a whole. Any othersection
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 asection
inside asection
. -
Select Add attribute in the Element Attributes Panel.
-
Enter
Role
and select it from the menu. -
Enter
accordion
as therole
attribute value. -
Select Save.
-
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 itssection
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 havexlink: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:
-
In the Content Manager, find the "parent" topic that contains the subsection ("child" topic). Select the "parent" topic to open it in the editor.
-
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.If you do not see an
import
element, it is likely that the subsection has been created in another way. For example, added as asection
element inside the "parent" topic. You can convert it into an inserted component by selecting itssection
element and then choosing Convert to reusable component. Paligo will convert thesection
into a separate topic and add animport
element in its place. -
Select the Edit tab in the toolbar.
-
Select Edit source code.
-
In the Source Code Editor, find the reference to the subsection topic ("child"). It is shown as an
xi:include
element and it contains anxi:fallback
element with apara
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 thexi:include
for the subsection you want to edit. -
Add
xlink:role="accordion"
to thexi:include
element. It should come after thehref
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>
-
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.
-
Select Save.
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:
-
In the Content Manager, select the "parent" topic that contains the subsection topic that has the accordion. Paligo opens the topic in the editor.
-
Select Preview and then HTML5.
Paligo opens a preview in an new tab.
-
Select HTML5.
-
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.
If you select the subsection topic's title or the arrow icon, it should expand the accordion, revealing the content in the topic.
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.