Use subsections to break up long passages of text into related pieces of information. This will help your audience to read and process your content more easily. It also allows them to quickly assess the information on a page by looking at the subsection's headings (subheadings). 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. Use the publication structure to control where the subsections appear. For details, see:
But the downside of this is that when you are editing, you can only see one section at a time. 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.
-
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).
Example 38. 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.
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.
Example 39. 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:
-
"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.
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 use components for subsections:
-
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 Create Subsections with Components.
-
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.
-
-
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.
Comments
0 comments
Article is closed for comments.