Using Heading Numbers

...

Section

Column

width	60%

Document Properties Marker

override	false

Short Description

A short introduction to use heading numbers with the projectdoc Toolbox.

Doctype

topic

hide

Name

Using Heading Numbers

Short Name

Parent

Parent Property

property-name	Name

hide

Audience

Name List

doctype	role
render-no-hits-as-blank	true
names	Author
property	Audience

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors

Sort Key

hide

Section

show-title	false
title	Description

Using heading numbers with the projectdoc Toolbox for Confluence is based on the Section Macro and a couple of space properties.

This short tip shows how to use this feature with projectdoc Documents.

Note that some features are only available for the projectdoc Toolbox of version 3.0 and later.

Section

title	Summary

Section

title	Prerequisites

This tip assumes that you know

what a Confluence space is
the basic use cases for the Section Macro
how to use document properties and space properties

Column

Panel

title	Contents

Table of Contents

maxLevel	1
indent	15px
exclude	Summary\|Prerequisites\|References\|Resources
style	none

...

Section

title	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 screenshot from the Confluence editor shows a section with two subsections

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.

Image RemovedImage Added

In order for heading numbers are shown, the numbering parameter must be activated for a section.

Image Removed Shows a screenshot of the macro editor with the parameter of the Section Macro to control heading numbers Image Added

Numbering activated 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.

Tip Box

title	More on Sections

For more information on how to use sections read the tip Section in Action.

...

Section

title	Switch on Numbers on Headings

To switch on numbers on headings use the property enable-heading-numbers Enable Heading Numbers. This can be used as a space property or a document property.

Section

title	Numbers on Space Level

When used as a space property, the numbering feature is on for all projectdoc documents in that space. To use heading numbering on space level, set enable-heading-numbers Enable Heading Numbers to true for instance on the space homepage.

Enable space properties on space level using the space property enable-heading-numbers

Caution Box

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

When delegation is used, all spaces delegating to the space with the property set to true are also using heading numbers.

Tip Box
For more information on space hierarchies please refer to the Space Hierarchies section in projectdoc Introduction.

Section

title	Numbers on Document Level

When used as a document property, heading numbers are only used on 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 Enable Heading Numbers to the document to add numbers to the document's section headings.

Enable heading numbers on space level using the space property 'enable-heading-numbers'

Note Box

This looks identical as when setting a space property on the space homepage.

It also implies, that heading numbers on the page homepage will activate heading numbers for all pages.

...

Section

title	Add Number to Document Title

Authors may choose to add a heading number to the title of all documents in a space by the space property use-document-heading-number Use Document Heading Number.

Enable heading numbers on document titles with the space or document property 'use-document-heading-number'

The same property name can be used on document level to only add heading numbers to the current document.

...

Section

title	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 pages that have purely navigation purposes such as documents of type Space Index.

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

Display Property

document	suppress-heading-numbers-on-doctypesSuppress Heading Numbers on Doctypes
property-name	Default 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

Note that this configuration can be overruled by enabling heading numbers on a particular document using enable-heading-numbers Enable Heading Numbers.

Section

title	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).

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.

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

Now the heading numbers are aligned since the Summary section is no longer showing a heading number.

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 sections collapsed. Printing is then no issue since there is no heading.

...

Section

title	Control the starting Number on a Document

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 over the numbering of headings on a number of documents.

Section

title	Sections in their own Documents

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, and
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. Then we use the Transclude Documents Macro to integrate them again with the original document by transclusion.

The following screenshot shows the transcluding document. The section 1 and parts of the section 2 are shown. The blue box around the transcluded sections are only visible to users with editing privileges.

Screenshot of the document using transclusion to include sections e

A section document looks like this:

The first section of the document as a separate document

Section

title	Configuration of Section Documents

To create the same heading number in the section documents as shown in the transcluding document, you need to set the number start (heading-number-startHeading Number Start) to 1. 2, and 3 respectively and switch on the numbering of the document title (set use-document-heading-number Use Document Heading Number to true).

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

The other section documents have the heading number started by 2 and 3.

Note Box

title	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 that is used by more than one document. In this case the numbering would need to be different for each transcluding document, which is not possible for the same document.

...

Section

title	Resources

Tour

render-no-hits-as-blank	true
render-as-definition-list	true
marker-column-property-name	Title
replace-title-with-name	true

Title	Short Description
Enable Heading Numbers
Use Document Heading Number
Suppress Heading Numbers on Doctypes
Heading Number Start
Heading Starting Level	enable-heading-numbers	suppress-heading-numbers-on-doctypes	heading-number-start	heading-starting-level
Section Macro
Transclude Documents Macro
HTML Macro	Macro provided by Confluence to add HTML code to a page. This macro is deactivated by default because of vulnerabilities that may be exploited.

Piwik Set Multiple Custom Variables

Name	Value
Department	projectdoc
Category	projectdoc-tip
Type	howto

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 20

New Version Current

Key

About

Keep up-to-date!

Powered by