- Created by Robert Reiner, last modified on 30. Jul 2018
projectdoc Toolbox
A short introduction the the Doctype Maven Plugin to generate Confluence Blueprints for projectdoc Doctypes based on an XML description.
Space Blueprints and Page Blueprints are a great tool in Confluence to boost productivity. Blueprints help to write information to a wiki more quickly and in a basically structured way. Not only is writing to the wiki much easier and more fun for authors, but also readers, familiar with the basic structure of a type of space or a type of document, find information by browsing easier and more quickly.
Guided Writing & clutter-free Reading
Thanks to the Section Macro and the Document Properties Marker Macro only those sections and properties that actually contain content are rendered.
This is what we call Guided Writing & clutter-free Reading since the author sees the elements in the editor, but they are not rendered to the reader in the view.
This short tip shows how to create page blueprints based on the projectdoc Toolbox with the free and open source Doctype Maven Plugin.
Doctypes and Blueprints
Document types – or doctypes for short – are page blueprints with some extras. These extras include:
- Each doctype provides document properties and document sections
- Each doctype provides – besides the regular Confluence index page – a separate homepage
- Each doctype provides properties commonly used, such as Short Description, Name, Subject, Categories, and Tags
- Each doctype provides a doctype-specific property called Type
- Each doctype provides commonly used sections such as Description, References, and Resources
Template authors and documentation architects are free to design their own properties and sections and define which ones are required and which ones are optional. What we describe here is how we designed our doctypes. These doctypes are available for free on the Atlassian Marketplace and can be forked due to their open source license on Bitbucket.
The Problem to solve
Creating page and space blueprints for Confluence is not difficult.
But it is quite time consuming to hunt down a type that prevents the add-on containing blueprints from starting successfully. This is related to the fact that you need to edit a couple of files where the author needs to be very careful to get the identifiers right. Otherwise the add-on simly does not get started in Confluence.
Also: teams that have defined a couple of standards for their blueprints (for instance named metadata or sections), typically need to replicate some code in each of the blueprint add-on projects. If any such standard changes, this change needs to be applied in a couple of places. Again this work needs to be done very carefully since the system won't report problems and misspellings overly accurately.
Our Solution to the Problem
We have defined a simple model for add-ons, spaces, and doctypes that can be specified with XML files. We provide XML schema files to support template authors in writing those models.
Based on the information of these models the Doctype Maven Plugin (a plugin to be run with Maven) generates an OBR or JAR with the blueprint add-on to be run on a Confluence server.
Let's have a look at an exmple doctype model!
<doctype
xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="cheat"
base-template="standard"
provide-type="standard-type"
category="default">
<resource-bundle>
<l10n>
<name>Cheat</name>
<description>
A brief solution to a problem.
</description>
<about>
Cheats are brief solutions to a problem. They are short, to the point,
and can be easily shared with your team.
</about>
</l10n>
</resource-bundle>
<properties>
<property key="projectdoc.doctype.common.type">
<value>
<macro name="projectdoc-name-list">
<param name="doctype">cheat-type</param>
<param
name="property"
key="projectdoc.doctype.common.type" />
<param name="render-no-hits-as-blank">true</param>
</macro>
</value>
</property>
<property key="projectdoc.doctype.cheat.level-of-experience-required">
<value>
<macro name="projectdoc-name-list">
<param name="doctype">experience-level</param>
<param name="property" key="projectdoc.doctype.cheat.level-of-experience-required" />
<param name="render-no-hits-as-blank">true</param>
</macro>
</value>
<resource-bundle>
<l10n>
<name>Level of Experience</name>
<description>
The level of experience expected the cheat addresses.
</description>
</l10n>
</resource-bundle>
</property>
</properties>
<sections>
<section key="projectdoc.doctype.common.description">
<resource-bundle>
<l10n>
<description>
Provide an optional overview over the context the cheat is applied
in.
</description>
</l10n>
</resource-bundle>
</section>
<section key="projectdoc.doctype.common.summary">
<resource-bundle>
<l10n>
<name>Summary</name>
<description>
Provide a solution to the problem.
</description>
</l10n>
</resource-bundle>
</section>
<section key="projectdoc.doctype.cheat.examples">
<resource-bundle>
<l10n>
<name>Examples</name>
<description>
Provide some examples on how the cheat looks like when applied.
</description>
</l10n>
</resource-bundle>
</section>
</sections>
<related-doctypes>
<doctype-ref id="asset" />
<doctype-ref id="todo" />
<doctype-ref id="event" />
</related-doctypes>
</doctype>
In this example you see a very slightly simplifed version of the Cheat doctype (see the current version of the doctype on Bitbucket). It defines two properties and gets a lot of standard properties inherited due to the reference to the standard base template. It also defines two sections and again, inherits a number of standard sections from the standard base template.
Due to the value of the provide-type attribute, another doctype, called Cheat Type, will be created. This will allow authors to categorize cheats with a doctype-specific type.
The doctype is associated with a default category. Doctype categories are used for grouping doctypes and render lists of references in a space homepage. Related doctypes – as you can see on the bottom of the XML document – are links rendered on homepages and index pages. Both structures support navigation and help readers to find information by browsing.
Limitations
This is just the start of a journey. There are still features that cannot yet be expressed with the XML models.
For instance the Module Type needs to list all documents with its type automatically. To specify such a section with a Display Table Macro running the query and listing the result set, you need to add plain XML of the storage format (xml element with the CDATA block inside).
<section key="projectdoc.doctype.module-type.modules-of-type">
<xml><![CDATA[ <ac:structured-macro ac:name="projectdoc-section">
<ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.module-type.modules-of-type"/></ac:parameter>
<ac:rich-text-body>
<ac:structured-macro ac:name="projectdoc-display-table">
<ac:parameter ac:name="doctype">docmodule</ac:parameter>
<ac:parameter ac:name="select"><at:i18n at:key="projectdoc.doctype.common.name"/>, <at:i18n at:key="projectdoc.doctype.common.shortDescription"/></ac:parameter>
<ac:parameter ac:name="where">$<<at:i18n at:key="projectdoc.doctype.common.type"/>> = [${<at:i18n at:key="projectdoc.doctype.common.name"/>}]</ac:parameter>
<ac:parameter ac:name="sort-by"><at:i18n at:key="projectdoc.doctype.common.sortKey"/>, <at:i18n at:key="projectdoc.doctype.common.name"/></ac:parameter>
<ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
</ac:structured-macro>
</ac:rich-text-body>
</ac:structured-macro>]]>
</xml>
<resource-bundle>
<l10n>
<name>Modules of this Type</name>
</l10n>
<l10n locale="de">
<name>Dokumentationsmodule dieses Typs</name>
</l10n>
</resource-bundle>
</section>
A second issue is controlling the wizard or adding validation using JavaScript. While there is a basic form with validation generated, more complex requirements need to be written to a plain Soy or JavaScript file and will override the generated code at the end of the process.
With this approach it is possible to use the plugin in a Maven build process and generate the required blueprints. Later new features can be added and the overriding parts can be replaced.
How to get started
If you are interested to give the Doctype Maven Plugin a try, then
- Start with the New User's Tour and have a look at Create a new Doctype Model – this will create a new project ready to add your descriptors for your add-on
- Have a look at the projectdoc Model Descriptors – this will help you understand the configuration options
- Checkout model projects on Bitbucket – see how things work
- Get familiar with Prerequisites and Project Settings – understanding these will make your configuration life easier
- Learn about Patching – to know how to work around limitations imposed by the plugin
- Understand use cases with Usage
Resources
- Doctype Maven Plugin
- Create doctype add-ons (OBRs) for the projectdoc Toolbox with Confluence Blueprints based on XML model descriptions easily!
- projectdoc Toolbox Online Manual
- The online manual for version 1 of the projectdoc Toolbox for Confluence.
- The projectdoc Toolbox for Atlassian Confluence
- The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.
