Versions Compared

Key

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

...

Section


Column


Document Properties Marker
overridefalse


Short DescriptionThe projectdoc Toolbox provides a number of features to help teams to reuse content. Content can be transcluded individually or in form of a multitransclude. Authors can even transclude content from multiple documents in the wiki, effectively combining transclusion with automatic lists.
 

Doctypetopichide
NameContent Reuse
 

Parent
Parent Property
propertyParent
property-nameName
 

Audience
Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesAuthor, Documentation Gardener, Documentation Architect
propertyAudience
empty-as-nonefalse
 

Level of Experience
Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesAdvanced Beginner
propertyLevel of Experience
empty-as-nonefalse
 

Expected Duration
30min
30 min
 

Subject
Name List
doctypesubject
propertySubject
 

Categories
Name List
doctypecategory
propertyCategories
 

Tags
Tag List
namesTransclusion
propertyTags
 

Iteration
Iteration
valuefilled
hide
Type
Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTip
propertyType
 

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

keywordstransclusion, excerpt, projectdoc Toolbox, tips, multi-excerpt, Confluence, add-on, modular documentation, reusehide
DC.subject
Display Property
property-namekeywords
hide
Sort Keyhide
enable-heading-numberstruehide




Column
width400px


Panel
titleContents

Table of Contents
outlinetrue
indent10px
excludeContent Reuse
stylenone



...

Section
titleDocument as the Building Block
Image Removed

A projectdoc document defines properties and sections. The projectdoc document is the base for most of the macros in the projectdoc Toolbox. Image Added

Properties are data and meta data of a document that teams define in tables with the Document Properties Marker Macro and the Document Properties Supplier Macro. This information is transcluded with the Display Document Property Macro and its cousins.

Sections define text to be transcluded by the Section Macro. Sections may have titles. Authors needing to refer to a chunk of content that is not a section use the Content Marker Macro. Content is transcluded by the use of the Transclusion Macro, the Transclude Documents Macro, and some related macros.

Since version 1.11 of the projectdoc Toolbox neither the transcluding document nor the document transcluded from is required to be a projectdoc document. 


Note Box
titleCompare to Confluence Macros

Confluence provides macros that work similar. Here is a short line-up including macros dealing with properties and sections.

While the Confluence macros are easier to use, the macros of the projectdoc Toolbox provide some additional features to make team collaboration and communication a lot easier.

For more information on this topic, please refer to Compare with built-in Features.

 



Tip Box
titleTip for an easy Start

To get started with projectdoc we recommend to use the projectdoc Blank Document for your experiments. It provides the basic structure of a projectdoc document with properties and sections.

For more advanced use cases consider to install one or more of the projectdoc doctype add-ons (especially the Core Doctypes). Install the doctype add-ons from the Atlassian Marketplace for free. They are also available on Bitbucket for customization.


...

Section
titleTransclusion Features

The projectdoc Toolbox supports the following transclusion use cases.

Section
titleMulti-Transclude from a Document

Authors may want to transclude more than one piece of content from a document. There may be a large document with information for novice and expert users. Both audiences may need the basic information. There may be some additional facts for novice users that may be of no interest for experts. And authors would like to give some hints for expert users that may just confuse beginners.

The Transclusion Macro allows to create two documents based on one document with its content tagged as 'common', 'novice' and 'expert'.

Note Box

Having one document with information for different audiences is not a silver bullet. It may help for some use cases, for instance if the number of content sections that is dedicated to one audience only is quite small, but not for all.



Section
titleTransclude from multiple Documents

Shows an example for multi-excerpt from three documentsEspecially for index documents or glossaries authors may need to transclude sections from a number of documents. The Transclude Documents Macro allows to define queries to match documents by their properties and then transclude sections from the documents in the result set.

There are specialized forms of this macro: Index Entries Table Macro and Index Card Macro to support creating documents like indices and glossaries.


Section
titleTranscluding with Heading Level

Authors often need to transclude content that is specified with a heading level of 1 to a section that is at level 2 or lower. The transclusion macros of the projectdoc Toolbox allow to specify the target level.

Example Box

Suppose a module defines a section with two subsections at the level of one. An author needs to transclude this section to the level of two. The author simply uses the Transclusion Macro and sets the target level to 2. The section will be rendered at the level of 2, its children at the level of 3.

From Confluence version 5.8 on, authors do not need to bother with the target level. Simply specify the asterisk ('*') and let projectdoc find the correct level. If the asterisk is defined as the target level, projectdoc will determine the level at which the transclusion is specified at request time.

Tip Box

The asterisk is especially handy if you decide to move the Transclusion Macro or the Section Macro in which the Transclusion Macro is some levels up or down. With the asterisk as the target level, simply drag-and-drop!



Section
titleTransclude into Table Cells

The Display Table Macro allows to reference documents in the form of a table. Authors map properties to table columns. They my also map sections to table columns.

Simply specify the name of the section as you would specify the name of a property. The value will be transcluded to the table column.

While the Display Table Macro fetches the list of documents that meet its search criteria on request time, the Tour Macro allows to render a table of documents. The author selects for each row in the table which document is rendered. The columns define the properties and sections to add.


Section
titleTrancluding Document Properties

Similar to transcluding sections the Transclusion Macro, the Display Table Macro (and its cousins) allow to excerpt one or more property values from a document.

Note Box

Currently it is only supported to transclude a property directly from a document. If that property is also transcluded, the property value will be shown, but it is not guaranteed that changes to the transient documents (that is: the not immediate referenced documents) will not be noticed by the transcluding document.



Section
titleTrancluding Space Properties

Properties may be defined on space level. Using the Display Space Property Macro allows to render the value. Note that due to the delegate-space Delegate Space authors may define hierarchies of spaces where the properties are inheritable.

For more information on space properties, please refer to Using Space Properties.


Section
titleModule Documents

Information can be transcluded from any document. If you want to define chunks of information, sometimes called topics, the Core Doctypes Add-on provides the Module document type. This doctype provides some standard properties and standard section. It also sections.

Image AddedImage Added

The Transcluded by section lists all documents that transclude content from the module automatically. Use Display Table for Transclusion References explains how to do this for your own documents.


...

Section
titleResources

More information on transclusion and related topics:

Tour
replace-title-with-nametrue


TitleShort Description
#Transclusion
 

Modular Documentation
Basic Concepts and Conventions for projectdoc
 

Hands-on Tutorial
 

Use Cases
 


The projectdoc Toolbox is  available on the Atlassian Marketplace!

...

Piwik Set Multiple Custom Variables


NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto