Create Subsections

You can create subsections so that you have topics inside other topics. Subsections are 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.

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

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:

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:

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,

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

The term "chunk" means that a topic has to be on its own. So if a topic is set to xinfo:chunk = yes, it cannot be a subsection inside another topic. If it is set to no, it can be a subsection.

Note

Chunking only applies to HTML outputs.

To set a topic's chunk value:

  1. Edit the topic in Paligo.

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

    Image showing Paligo editor with the Element Structure Menu shown below the toolbar options. The section element is selected and there is a drop-down menu. The Go to Element option is selected.
  3. In the Element attributes section, add the xinfo:chunk attribute and set its value.

    • Yes to prevent the topic from being a subsection

    • No to allow the topic to be a subsection.

    xinfo-chunk.png
  4. Select Save.

When you publish, the topics that have xinfo:chunk set to yes will always be on separate pages. They cannot be subsections on another page.

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. You do this under "TOC and chunking" in the Layout Editor:

  • Use the xinfo:chunk attribute on the section element in a topic.

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

Let's say 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.

mars-travel-levels.png

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 Insert > Component and choose the topic that you want to add as a subsection.

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

    insert-topic-component.jpg
  4. Repeat steps 2 and/or 3 for each of the subsections you want to add and save each topic.

  5. 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, with this technique, you cannot reuse the subsection in other topics. (To reuse the subsection, you would first need to convert it into a component).

To add a second section element as a subsection:

  1. Position the cursor so that it is a direct descendant of the main topic's section element. It must not be inside another element. For example, if you position the cursor in a paragraph inside the main section, the element structure menu will show section > para. For the subsection, you need to position the cursor outside of any other block elements so that the element structure menu shows section > .

    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.

    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

    All of the content in a topic must be inside the <section> and </section> tags of the main topic. This includes any subsections that you add.

  2. Display the element context menu.

  3. Search for section and then select it.

    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.