Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleAdditional Control

For some use cases you may need additional control on heading numbers.

Section
titleSuppress Heading Number per Doctype

If you choose to have heading numbers for all documents you have enabled the heading numbers on space level. You may not want numbers on page that have purely navigation purposes such as documents of type Space Index.

In this case use the space property suppress-heading-numbers-on-doctypes to switch off heading numbers for a selected set of document types. Per default

Display Property
documentsuppress-heading-numbers-on-doctypes
property-nameDefault Value
are included in the set of documents that should not have heading numbers.

Controls to suppress heading number for all documents of type 'topic' in this space

Not that this configuration can be overruled by enabling heading numbers on a particular document using enable-heading-numbers.

Section
titleSuppress Heading Number on a Section

You may not need a heading number on a section for your document. Like in the following example where the table of contents does not show the summary (and therefore does not number it).

Screenshot of a page where the Summary section has a heading number, but is not shown in the table of contents

Since the Summary section is not referenced in the table of contents (upper right side of the screenshot), the numbers differ. To align them, you either need to show the Summary section in the table of contents or suppress the heading number for the Summary.

Deselect the parameter Numbering in the macro editor for the Section Macro showing the Summary.

Shows a screenshot of the Numbering parameter is set to 'false' (unchecked)

Now the heading numbers are aligned.

Screenshot of the document with the heading number aligned

Note Box

Note that in case you need to print the document, the summary has a numbered heading.

To prevent this issue, you may choose to not show the title and have the Description and the Summary section collapsed. Printing is then no issue since there is no heading.

Section
titleNumber and Level Start

In case you have a large document, like a specification or a architecture description using the arc42 Template, you may need more fine grained control of the numbering of a page.

Section
titleExtracting Section

Suppose you need to extract the sections Space Relation, Providing Spaces, and Collaboration Spaces to their own documents. This way you may have easier content reuse, you may collaborate easier if each content is created by another author, any you may reference the individual sections easier if they have their own unique URL.

Let's use the Section Doctype to create a document for each of the three sections we extract and the Transclude Documents Macro to integrate them with the original document.

Screenshot of the document using transclusion to include sectionse

A section document looks like this:

The first section of the document as a separate document

Section
titleConfiguration of Section Documents

To create the same heading number as in the transcluding document, you need to set the number start (heading-number-start) to 1.0 and the heading starting level (heading-starting-level) to 2.

Two properties to control the heading numbers

Now the section headings align with the numbers shown in the transcluding document.

The aligned heading numbers of the first section

Note Box
titleOnly works for strict structures

Now the topic is closely bound to the document it is transcluding. In the case of sections this is typically okay. But you would need to update the document properties in case you alter the position of a section in the transcluding document.

There is no control in case you have a Module or a Topic since in this case the numbering would be different for each transcluding document.

The configuration for the second transcluded section requires the number start (heading-number-start) to be set to 2.0.

Configuration of document properties for the second section

The rendered document would render like this:

Screenshot of the second section in its own document

Section
titlePage Title Numbering

As you may already have notices, the numbering of the section does still not align. Headings have no numbers per default.

To change this you need to apply a CSS style to your Confluence site configuration or to your space configuration. This CSS may be different according to your layout tool you employ.

Here is one way to achieve the heading numbering for the transcluding document and all its sections for a standard Confluence environment. Using a layout tool may make the issue much simpler.

Section
titleActivate the HTML Macro

To add additional CSS styles you need to activate the HTML Macro provided by Confluence as a system plugin.

Caution Box

HTML macros are disabled by default

The HTML macro will only be available if it has been enabled by an administrator. Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks.

Shows the enabled HTML Macro

Section
titleOption 1: Set Heading Number per Default

If you set the heading number per default, then each page will have a heading number.

Section
titleSpace Look and Feel

Using the Space Tools you are able to configure the CSS for a single space in Confluence.

Stylesheet configuration for the space look and feel

Code Block
languagecss
h1#title-text:before {  
   counter-increment: h1;  
   content: counter(h1) " ";  
}

If you use level one headings on the page, these will continue with the second number. So you would need to use only level two headings on your pages. Besides that you also have numbers where you probably do not want them as in the screenshot shown above. "Space Tools" also uses the "title-text" identifier and therefore has a heading number.

Section
titleSuppress Heading Numbers on Transcluding Page

To remedy some of the issues above, use the following CSS

Code Block
languagecss
h1#title-text:before {  
counter-reset: h1 !important;
counter-increment: none !important;
content: "" !important;
}

with the HTML Macro.

HTML Macro with style element and CSS

Section
titleOption 2: Use Custom CSS on every transcluded Page

Add the following CSS to every page you need a heading number in the title.

HTML Macro for transcluded Documents

Since you already use level 2 headings (heading-starting-level) these won't interfere with the h1 used for the title.

You do not need a configuration for the space's Look and Feel (Stylesheet).

No Stylesheet configuration required

And you won't need a special treatment for you transcluding pages.

Transcluding page with heading numbers, but not for the title.

The heading numbers are enabled (the space property is not hidden in the screenshot), therefore the sections have heading numbers. The page title is considered as the title of the document and therefore has no heading number.

Section
titlePros and Cons

If you have a dedicated space for your specification or software architecture document, option 1 may be easier to use. Mind unwanted numbering on standard pages, but otherwise you would not need to configure the section pages with an additional HTML Macro.

In every other case the second option might be easier to handle, since there are less side effects and there is only one additional HTML Macro on each document that is using a dedicated heading number.

...