Improved Support for Templates, Support for Web API, improved Transclusions
Today we released version 1.13.0 of the projectdoc Toolbox on the Atlassian Marketplace!
projectdoc is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation.
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com
.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com
)!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.
New and Noteworthy
The following changes may be the most interesting of this release.
Web API Support
The Web API Extension in version 1.1 now supports write access to projectdoc documents. This version of the projectdoc Toolbox is providing services for this extension.
Key | Summary | T | P | Status | Resolution | Description |
---|---|---|---|---|---|---|
PDEXWAPI-1 | Support Document Manipulation |
|
|
Done | Fixed |
Provide services to change projectdoc documents. |
PDEXWAPI-2 | Cache Refresh |
|
|
Done | Fixed |
We need to signal that clients need to check for updated content. Currently we simply set the last modification time and (for Confluence 5.10.x) the ETag. Now we need to set the CacheControl to instruct clients to revalidate. |
PDEXWAPI-3 | Breaking CDATA Blocks |
|
|
Done | Fixed |
Updating a page with the API removes CDATA blocks from the page. This corrupts for instance the Code Macro or the HTML macro. Before: <ac:plain-text-body><![CDATA[<a class="aui-button sharelinks-urlmacro-button" href="a"><span>reader</span></a> <a class="aui-button sharelinks-urlmacro-button" href="b"><span>writer</span></a> <a class="aui-button sharelinks-urlmacro-button" href="c"><span>printer</span></a>]]></ac:plain-text-body> After: <ac:plain-text-body><a class="aui-button sharelinks-urlmacro-button" href="a"><span>reader</span></a> <a class="aui-button sharelinks-urlmacro-button" href="b"><span>writer</span></a> <a class="aui-button sharelinks-urlmacro-button" href="c"><span>printer</span></a></ac:plain-text-body> |
Enhanced Remote Transclusion
The Information Systems Extension in version 1.1 supports Transclusion of HTML fragments.
Key | Summary | T | P | Status | Resolution | Description |
---|---|---|---|---|---|---|
PDEXINFOSY-9 | HTML System Transclusion |
|
|
Done | Fixed |
Support transclusion from XML/HTML documents by query. |
PDEXINFOSY-8 | HTML Element Transclusion Macro |
|
|
Done | Fixed |
Allow to transclude HTML content from a remote server by ID and selector. |
PDEXINFOSY-10 | Allow Rendering of Full URL |
|
![]() |
Done | Fixed |
For the generic and site link macros allow to render the full URL instead of the last part of the URL. |
PDEXINFOSY-11 | Suppress Duplicate Slash in URL Rendering |
|
![]() |
Done | Fixed |
If either the system URL ends with a slash or the file starts with a slash then do not render an additional slash. |
Template Support
This version allows users to create user templates with projectdoc macros. The way previous versions of the projectdoc Toolbox handled previews prevented the template editor from being used.
Please note that the source editor often still corrupts the template source, so its use is not recommended.
The free projectdoc blueprints typically use variables inside macro definitions. This does not cause any problems when used outside the template editor. The template editor does not allow placeholders inside macro definitions, so it will corrupt templates that use them. Therefore: do not edit blueprint templates that use placeholders with the template editor!
Breaking Changes
The following changes are incompatible with the previous release.
Disblock Property Values per Default
Since the Confluence editor may add a number of block elements without giving the user means to edit it (without the source editor plugin) we decided to run some automatic correction per default.
The correction will normalize the property value prior to saving it. The normalization will remove redundant div
and p
elements.
This will make it easier for users to get what they want.
If the property value is indeed a block element, the new control is-block
will prevent the element from being disblocked.
If users are generally unhappy with this breaking change, the system property prevent-disblocking-property-values
will help them to switch this off. This system property needs to be set on start time of the Confluence server.
Note that since we will now remove the blocks per default, we may break the runtime behavior. If a user really needs the block element s/he may either save the value with the is-block
control or needs to switch off this feature with the system property.
See
PDAC-676
-
Disblock Property Values per Default
Done
for tracking this issue.
Last Version and Last Version Comment
Since is a number of new artificial properties, existing documents need to be indexed to have these properties available.
Users who do not access these values or only require them for new documents do not need to run the reindex.
See
PDAC-693
-
Provide Access to Last Version and Last Version Comment
Done
for tracking this issue.
Upgrade Instructions
The following topics have to be considered for an upgrade to this version.
The Maven Extension and the related doctype add-ons have been removed in 2025.
It is recommended to generate the information in other information systems (for instance Maven Sites) and then link from Confluence to these pages.
It is recommended to update extensions and doctype add-ons to the latest versions.
Add-on | Type | Version |
---|---|---|
Web API Extension | Extension | 1.1 |
Information Systems Extension | Extension | 1.1 |
Maven Extension | Extension | 1.0.2 |
Core Doctypes | Blueprints | 6.1.0 |
Software Development Doctypes | Blueprints | 6.0.2 |
projectdoc Add-on for arc42 | Blueprints | 4.1.1 |
Developer Diaries | Blueprints | 4.0.2 |
Doctypes for Agile Planning | Blueprints | 5.0.1 |
projectdoc for Maven Developers | Blueprints | 2.0.1 |
projectdoc for Java Developers | Blueprints | 2.1.0 |
Please note that the Doctypes for Project Management are available soon!
List of Changes
The complete list of changes for this release.
The following changes are part of the latest projectdoc Toolbox for Confluence.
Key | Summary | T | P | Status | Resolution | Description |
---|---|---|---|---|---|---|
PDAC-690 | Support Template Previews for Document Properties Marker Macro |
|
|
Done | Fixed |
We should consider to provide previews for the Document Properties Marker Macro in the context of the template editor. Otherwise it cannot provide access to the template variables. |
PDAC-676 | Disblock Property Values per Default |
|
|
Done | Fixed |
Since the editor may add a number of block elements without giving the user to edit it (without the source editor plugin) we should run the correction per default. The correction will normalize the property value prior to saving it. The normalization will remove redundant div and p elements. This will make it easier for users to get what they want. If the property value is indeed a block element, the new control is-block will prevent the element from being disblocked. If users are generally unhappy with this breaking change, a system property will help them to switch this off. This system property needs to be set on start time of the Confluence server. Note that since we will now remove the blocks per default, we may break the runtime behaviour. If a user really needs the block element s/he may either save the value with the is-block control or needs to switch off this feature with the system property. |
PDAC-695 | Allow multiple References in the Reference Property Macro |
|
![]() |
Done | Fixed |
If the referencing property refers to multiple documents, we should render the referenced property of all documents. |
PDAC-692 | Provide Page Preview for Document Properties Marker Macro |
|
![]() |
Done | Fixed |
Preview of properties should help users to check updates to properties. |
PDAC-682 | Version the automatic Store of a Page |
|
![]() |
Done | Fixed |
Currently all automatic stores will write over the current version. With the advent of the web api we need to make sure that users can roll back the versions created with this api. |
PDAC-680 | Index Heading Print Quirk Mode |
|
![]() |
Done | Fixed |
Provide a print quirk mode for rendering the index in h1 elements (instead of span). |
PDAC-671 | Support Property References in Transclusion Macros |
|
![]() |
Done | Fixed |
The Transclusion Macro and the Transclude Documents Macro supports placeholders with simple key-value mappings. We should also support to have a property reference as a value which is resolved in the context of the transcluding page. |
PDAC-670 | Transclusion with Page and Space Properties |
|
![]() |
Done | Fixed |
It should be possible to employ document and space properties from the document that is using the Transclusion Macros as values for placeholders. |
PDAC-693 | Provide Access to Last Version and Last Version Comment |
|
|
Done | Fixed |
Add Version Number, Version Comment, Last Version Comment, and Last Version Number with Comment as artificial properties. |
PDAC-683 | Typed Parent Calculation bent to Confluence Parent Hierarchy |
|
|
Done | Fixed |
The typed hierarchy of parents is currently bound to the Confluence page hierarchy. It simply a filter on that hierarchy that matches the doctype of the parent document. If it is the same, the parent is accepted as typed parent, otherwise it is not and the calculation stops. But the Parent Property of projectdoc does not need to be related to this hierarchy. The parent may reference any other document and so identifies this page as its logical parent. The value of the Parent Property may either be a regular Confluence link or it may be the Parent Property or the Display Property Macro. These references should be accepted to create the artificial properties AncestorTypeNames and (new) AncestorTypeIds. |
PDAC-696 | Ancestors should not contain the Document |
|
![]() |
Done | Fixed |
The list of ancestors should only contain the ancestors, not the document whose ancestor list this is. |
PDAC-691 | Allow Preview of Sections in Template Editor |
|
![]() |
Done | Fixed |
The Section Macro fails to render in the preview of the template editor. |
PDAC-685 | Add Box Titles to Lucene Index |
|
![]() |
Done | Fixed |
The titles of box macros are not added to the Lucene index and therefore not searchable. We need to handle the titles of boxes as we handle the titles of sections. |
PDAC-678 | Allow composed Space Properties for Code Macro |
|
![]() |
Done | Fixed |
Currently the Code Macro does not resolve space properties that contain space property placeholders. But these templates should be resolved as it is done by the Display Space Property Macro. Meanwhile composed space property values can only be created by the use of the display space property macro. |
PDAC-668 | Allow to override Attribute Names in Space List Macro |
|
![]() |
Done | Fixed |
To be similar to the Display Table Macro also allow heading translations for the Space List Macro. Simply specify, e.g., title=My Title to render My Title instead of the localized translation of title. Also allow to set the empty string. |
PDAC-667 | Allow Spaces to be selected with AND using the Space List Macro |
|
![]() |
Done | Fixed |
The space list macro only allows to specify a list of categories where any category may match to select a space. We should allow to specify categories where a space has to match all of them to be selected. |
PDAC-699 | Support References for Quote Documents |
|
|
Done | Fixed |
The quote macro has to consider a reference provided by the quote doctype. This makes it easier to create referenceable documents containing quotes. |
PDAC-698 | Quote Date without Brackets |
|
|
Done | Fixed |
Provide a space property to control the rendering of brackets around the date of the quote macro. If the date is rendered using the date picker, the additional brackets need to be removeable. |
PDAC-665 | CSS Class for Sections without Title |
|
|
Done | Fixed |
To allow specific handling of sections that have their title suppressed, render a CSS class. |
PDAC-681 | Page Manipulator cannot handle CDATA |
|
|
Done | Fixed |
When the page manipulator parses a page the CDATA blocks are transformed to escaped entity text. This breaks for instance macros that contain CDATA blocks and after the page is written do not recognize these blocks any longer. We need to encode the CDATA blocks so that the underlying parser cannot corrupt the page content. |
PDAC-672 | Page Property Generation |
|
|
Done | Won't Fix |
Due to an API change projectdoc does not provide the document properties as page properties. |
PDAC-701 | Level Calculation for Transclusion fails |
|
![]() |
Done | Fixed |
Transcluding documents fails to render the 0-heading correctly. The heading is rendered at level 1 instead of suppressing the heading. |
PDAC-697 | Quote Authors not collected with Lucene |
|
![]() |
Done | Fixed |
When Lucene runs the rendering to index a page, the references to quote authors are not calculated. |
PDAC-694 | Render as Definition List |
|
![]() |
Done | Fixed |
Setting definition list as render option for the Document Properties Marker Macro does not always render a definition list. |
PDAC-689 | Template Preview renders wrong Message |
|
![]() |
Done | Fixed |
The Document Properties Marker Macro renders an error message indicating that there is no document to be rendered when the preview of a template is shown. Since projectdoc currently does not support previews, the message should just state that. |
PDAC-686 | Prevent Section Titles of empty Sections from being indexed |
|
![]() |
Done | Fixed |
If the section contains only a placeholder, the body is effectively empty, but the section is considered non-empty. This results in titles of empty sections to show up in the index. |
PDAC-684 | Dots in Section and Content Marker IDs |
|
![]() |
Done | Fixed |
If the identifier of the Section Macro or the Content Marker Macro contains a dot where only digits follow, the content cannot be transcluded. For instance "Xyz 1.1" cannot be transcluded, but "Xyz 1.x1" or "Xyz 1.1x" can be transcluded. |
PDAC-679 | Artificial URL Properties not available in Properties Table |
|
![]() |
Done | Fixed |
The artificial properties that references URLs are not available during the rendering of the properties within the Document Properties Marker Macro (or the supplier macro). This is because the URL values are derived from the document after the regular properties have been rendered. |
PDAC-677 | Boxing Issue with Text in div Element |
|
![]() |
Done | Fixed |
If the content of a div element having a class attribute value of "content-wrapper" is text, the unboxing will not remove the div. We want the div element containing the class attribute to be always removed. |
PDAC-675 | Replacement fails in Transclusion if ID contains Umlauts |
|
![]() |
Done | Fixed |
Replacement fails if placeholder contains characters that are translated to HTML-Entities. This is only evident if the content is moved to another section level. |
PDAC-673 | Rendering Properties Table in Definition List and Printer Mode |
|
![]() |
Done | Fixed |
If the Document Properties Marker Macro is set to definition list, in printer render mode the rendering is broken. Parts of the CSS classes are rendered as text. The end of the tag seems to be determined wrongly. |
PDAC-666 | Duplicate Spaces shown in Space List Macro |
|
![]() |
Done | Fixed |
The space list macro lists spaces that match multiple categories multiple times. Each space should be listed only once. |
PDAC-662 | Exact Match Queries only work on projectdoc Documents |
|
![]() |
Done | Fixed |
Exact queries should work on all pages. If you use a query like $<Tags>=[Xxx] then Lucene is complaining about the syntax iff the page is not a projectdoc document. |
PDAC-661 | Render Authors as String in Quote Macro |
|
![]() |
Done | Fixed |
If authors are rendered as a list and not as a list of comma-separated-values, the quote macro renders the names of the authors also as a list. If the authors are stored in a list, the authors should also be rendered as a list of comma-separated-values. |
PDAC-334 | Page Preview does not work |
|
![]() |
Done | Duplicate |
The preview shows the information from the last saved page. |
PDAC-700 | Broken Blueprint and Space Blueprint Icons for IE and Firefox |
|
|
Done | Fixed |
The blueprint icon for projectdoc Blank Document, projectdoc Demonstration Space and projectdoc Starter Space are not displayed for IE and Firefox. |
PDAC-688 | Remove Sort-By from the Name List Body Macro |
|
|
Done | Fixed |
The sort-by parameter is shown although it has no effect. It should be removed. |
PDAC-687 | Version URLs of Change Log Macro |
|
|
Done | Fixed |
The URLs to the versions rendered in the change log macro are null. Sometimes they point to the wrong resource. |
PDAC-669 | Add missing docs for Identifier Property in Transclusion Macro |
|
|
Done | Fixed |
The transclusion macro provides the Identifier property which lacks documentation. The identifier is used to render an HTML identifier. |
Resources
- Release Notes for the projectdoc Toolbox
- Relevant information on changes to the projectdoc Toolbox for Confluence introduces by new versions of this app.
- Glossary
- Terms used in and defined for projectdoc.
- FAQs
- Questions and answers related to the projectdoc Toolbox and Confluence.