A short introduction to use heading numbers with the projectdoc Toolbox.
Use Sections
Authors need to use sections to organize content in a projectdoc Document. This is required to use the numbering feature of the projectdoc Toolbox.
The subsections are contained in their parent section. The level of each section is defines as '*'. Therefore the projectdoc Toolbox will calculate the correct heading level automatically.
In order for heading numbers are shown, the numbering parameter must be activated for a section.
This is the default value. Therefore authors do only need to configure the macro here, if the heading numbers for the sections must not be shown. Please note that checking this checkbox only tells the projectdoc Toolbox that in case heading numbers are activated that this sections should have a number. If heading numbers are not activated, then this parameter has no effect.
Switch on Numbers on Headings
To switch on numbers on headings use the property enable-heading-numbers. This can be used as a space property or a document property.
Numbers on Space Level
When used as a space property , the numbering feature is on for all projectdoc documents in the space. When delegation is used, all spaces delegating to the space with the property set to true are also using heading numbers.
For more information on space hierarchies please refer to the Space Hierarchies section in projectdoc Introduction.
To use heading numbering on space level, set enable-heading-numbers to true for instance on the space homepage.
Copy-and-Paste -- may be a problem!
The projectdoc Toolbox takes the values you enter as property names, values and controls as is. If you add HTML markup for any reason, the projectdoc Toolbox assumes that you know what you are doing. In case you copy-paste text from a page shown in your browser, there may be markup you do not want to paste. Be careful here!
For more information please have a look at Cannot access Property from a Document.
Numbers on Document Level
When used as a document property, heading numbers are only used for this document. This allows for a more fine grained control since heading numbers are not relevant for every page shown online.
Add the property enable-heading-numbers to the document.
This looks identical as when setting a space property on the space homepage. This implies, that heading numbers on the page homepage will activate heading numbers for all pages.
Add Number to Document Title
Authors may choose to add a heading number to the title of the document by the space property use-document-heading-number. The same property name can be used on document level. In the first case every document in a space will provide a heading number for the title, in the second case the feature is only applied to the current document.
Additional Control
For some use cases you may need additional control on heading numbers.
Suppress 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 are included in the set of documents that should not have heading numbers.
Not that this configuration can be overruled by enabling heading numbers on a particular document using enable-heading-numbers.
Suppress 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).
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.
Now the heading numbers are aligned.
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.
Number 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.
Extracting 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.
e
A section document looks like this:
Configuration 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.
Now the section headings align with the numbers shown in the transcluding document.
Only 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.
The rendered document would render like this:
Page 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.
Activate the HTML Macro
To add additional CSS styles you need to activate the HTML Macro provided by Confluence as a system plugin.
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.
Option 1: Set Heading Number per Default
If you set the heading number per default, then each page will have a heading number.
Space Look and Feel
Using the Space Tools you are able to configure the CSS for a single space in Confluence.
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.
Suppress Heading Numbers on Transcluding Page
To remedy some of the issues above, use the following CSS
h1#title-text:before {
counter-reset: h1 !important;
counter-increment: none !important;
content: "" !important;
}
with the HTML Macro.
Option 2: Use Custom CSS on every transcluded Page
Add the following CSS to every page you need a heading number in the title.
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).
And you won't need a special treatment for you transcluding pages.
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.
