Versions Compared

Key

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


Section


Column
width70%60%


Document Properties Marker
overridefalse


Short DescriptionA short introduction to use heading numbers with the projectdoc Toolbox.
Doctypetopichide
NameUsing Heading Numbers
Short Name
Parent
Parent Property
property-nameName
hide
Audience

Name List
doctyperole
render-no-hits-as-blanktrue
namesAuthor
propertyAudience


Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
propertyCategories

Tags

Tag List
namesheading-number
propertyTags


FlagsConfluence, projectdoc Toolbox, heading numbers, sectionshide
Iteration

Iteration
valuefocused

hide
Type

Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTip
propertyType


Level of Experience

Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesCompetent
propertyLevel of Experience


Expected Duration
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors

Sort Keyhide
Column
Panel
titleContents

Table of Contents
indent15px
excludePrerequisites|Resources
stylenone



Section
show-titlefalse
titleDescription

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.

Some

Note that some features are only available

since

for the projectdoc Toolbox of version 3.0 and later.


Section
titleSummary



Section
titlePrerequisites

This tip assumes that you know

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



Column


Panel
titleContents

Table of Contents
maxLevel1
indent15px
excludeSummary|Prerequisites|References|Resources
stylenone




Section
titleUse 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.

Shows a screenshot of the macro editor with the parameter of the Section Macro to control heading numbersImage RemovedShows a screenshot of the macro editor with the parameter of the Section Macro to control heading numbersImage Added

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

projectdoc-box-tip
titleMore on Sections

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



projectdoc-section
titleSwitch 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
titleNumbers 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.

Tip Box

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

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

projectdoc-box-tip

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



Section
titleNumbers on Document Level

When used as a document property, heading numbers are only used for 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-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'Image Modified

Note Box

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

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




Section
titleAdditional ControlAdd 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.

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

The same property name can be used on document level to only add heading numbers to the current documentFor 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

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-doctypes

Suppress 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 spaceImage Modified

Not

Note that this configuration can be overruled by enabling heading numbers on a particular document using

enable-heading-numbers

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 contentsImage Modified

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)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 alignedImage Modified

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

sections collapsed. Printing is then no issue since there is no heading.



Number and Level Start
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

of

over the numbering of headings on a

page

number of documents.

Extracting Section
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

  1. you may have easier content reuse,
  2. you may collaborate easier if each content is created by another author,
any
  1. and
  2. 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

. 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 sectionsImage Modifiede

A section document looks like this:

The first section of the document as a separate documentImage Modified


Section
titleConfiguration 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-start

Heading Number Start) to 1.

0 and the heading starting level (heading-starting-level) to 2.Two properties to control the heading numbersImage Removed

2, and 3 respectively and switch on the numbering of the document title (set Use Document Heading Number to true).

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

The aligned heading numbers of the first sectionImage Removed

Image Added

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

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.

, which is not possible for the same document.

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

that is used by more than one document. In this case the numbering would need to 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 sectionImage Removed

The rendered document would render like this:

Screenshot of the second section in its own documentImage Removed

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 MacroImage Removed

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 feelImage Removed

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 CSSImage Removed

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 DocumentsImage Removed

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 requiredImage Removed

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

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

Section
titlePros and Cons




Section
titleSubordinate Topics
Display Table
doctypetopic
render-no-hits-as-blanktrue
render-modedefinition
selectName, Short Description
restrict-to-immediate-childrentrue
sort-bySort Key, Name

...

Section
titleResources


Tour
render-no-hits-as-blanktrue
render-as-definition-listtrue
marker-column-property-nameTitle
replace-title-with-nametrue





Piwik Set Multiple Custom Variables


NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto