- Created by Robert Reiner, last modified on 17. Nov 2022
projectdoc Toolbox
This is a gentle introduction to the core macros. The macros are grouped semantically to make it easier for users to build a conceptual mind map for them.
- Level of Experience
Working Horses
Authors add properties and sections to projectdoc documents. This information is transcluded from other documents, either by pointing to a particular property or section or by defining a query to select information from a number of documents.
To enhance navigation authors may render links to related documents by queries. If the list of references is fixed, the documents to link to can be easily defined and any property or section may be rendered.
The following macros are used to accomplish these tasks quite easily.
| Name | Short Description | Notes |
|---|---|---|
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property. | Typically this macro is already on every projectdoc document created with a blueprint. Authors supply values for the defined properties and optionally add new ones. | |
Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content. | Defines a section within a projectdoc document. This is text content with a title to be easily transcluded for reuse in other pages. | |
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | Since every document has properties, it is very easy to select them. Mind the Search Tips! | |
Renders a predefined list of documents in a table. | While the Display Table Macro lists a result set of documents that match your queries, the Tour Macro allows to select the documents to display manually. Then select the properties and sections you want to show. | |
Transcludes content from a document marked with the content marker macro. | If you need to transclude from a single document. Also consider to have a look at the Section Macro if you want to transclude information from a non-standard part of a document. | |
Renders transcluded content fetched from documents of a result set. | If you need to transclude from documents in a result set. | |
Renders the value of a property of a document. | To render the value of a document property. If you need to render more than one property of a document, have a look at Display Document Properties Macro that allows you to specify a template. Note that there is also a variant for space properties: Display Space Property Macro. | |
Renders a quote from a resource with author and source. | To quote relevant information, also consider the External Quote Macro for quoting from resources outside your wiki. |
For teams to work collaboratively on their documentation there are more use cases than these basic ones. You may need to transclude information from remote servers, add visuals to put emphasis on important information, or control which information to show for different audiences.
Have a look at the next section to learn of these and all the other macros inside of the projectdoc Toolbox!
Introduction to Core Macros
The list groups the core macros semantically. This may help new users to learn about the core macros and to know when to use which.
- Referencing Macros
- Macros to help authors to reference other documents that are relevant to the current document.
- Structuring Macros
- Macros to help authors to a document structure so that the information is easier to understand.
- Modular Documentation Macros
- Macros to support single sourcing for creating modular documents.
- Visual Macros
- Macros to render information in a visually appealing format.
- Document Development Macros
- Macros that help authors to create templates and content.
- Collaboration Macros
- Macros to support a team to write their documentation collaboratively.
What's next?
If you not already got your hands dirty, you may choose to work through the Hands-on Tutorial. If you do not already have the projectdoc Toolbox up and running, you may want to check the Installation Guide first.
Otherwise you may take a tour, browse the online manual by reference, or learn interesting aspects of the projectdoc Toolbox by browsing the Tips.
Take a Tour
Checkout some of our tours:
| Name | Short Description | Audience |
|---|---|---|
| Tour for Document Authors | Tour through the documentation for users who want to learn to create documents based on projectdoc doctypes. | Author |
| Tour for Template Authors | This is a tour through the documentation for users that want to design their own set of templates or just want to create one or two templates. | Template Author, Documentation Architect |
| Collecting Information | Get users started with collecting external information that is relevant for their project. Each piece of information is referenced by a resource document. Excerpts and quotes are used to catch detailed information and make it referenceable. | Documentation Architect, Author |
| Features on one Page | The list of features of the projectdoc Toolbox on a single page. | |
| Quick Start to learn projectdoc in 4 Steps! | More than a short introduction, this tutorial introduces the need-to-know basics to get started with projectdoc. | Author |
| Reference Tour | This tour provides a list of links to reference material. | Author, Confluence Administrator, Documentation Gardener, projectdoc Developer, Template Author |
| Tour for Software Developers | Overview over the most relevant information for software developers to create their documentation on Confluence with the projectdoc Toolbox. | Documentation Architect, Author, Documentation Gardener |
Browse by Reference
The reference pages give you an overview over configuration and usage options. Especially the overview over the space properties provide an interesting reference of configuration options.
| Name | Short Description | Audience |
|---|---|---|
| Query Configuration | Controls the parameter to use for running queries with the projectdoc Toolbox. | Confluence Administrator, Documentation Architect, Documentation Gardener |
| Dynamic Property Value Handling | Configuration to control how the projectdoc Toolbox handles property values with dynamic content. | Confluence Administrator, Documentation Architect, Documentation Gardener |
| Artificial Properties | In addition to the properties specified in the document properties table, projectdoc provides additional properties drawn from Confluence or metadata. | Author, Documentation Architect, Documentation Gardener |
| Blueprint Properties | Lists the configuration options for template authors to control page creation. | Template Author, Documentation Architect, Documentation Gardener |
| Cache Refresh Actions | projectdoc documents are stored in caches for quick access. Users may want to clear one of these caches. | Confluence Administrator, Documentation Gardener, projectdoc Developer |
| Configuration | Information for the configuration options of the projectdoc Toolbox. | Confluence Administrator, Documentation Architect, Documentation Gardener |
| CSS Styles | Lists CSS selectors provided by the projectdoc Toolbox to apply styles. | Documentation Architect, Confluence Administrator |
| Doctypes Overview | List of all doctypes provided by add-ons. Provides an overview over doctype IDs and blueprint keys. | |
| Document Property Controls | Lists valid controls for properties to be used in document properties tables. | Author, Documentation Architect, Documentation Gardener |
| Information System Macros | List of macros linking to or transcluding from external information systems. | Author, Documentation Architect |
| List of Services | Lists all services provided by the Web API Extension. | |
| Logging | List of loggers for monitoring projectdoc. | Confluence Administrator |
| Lucene Search Fields | Names for fields added to the Lucene search index. | |
| Page Wizard Placeholder | The pages wizards provide placeholder to make page creation easier. | Template Author |
| projectdoc Doctype Add-ons | Doctype add-ons provide space and page blueprints based on macros from the projectdoc Toolbox. | Documentation Architect |
| projectdoc Extensions | Extensions augment the projectdoc Toolbox. Features that are not relevant for all users are separated and may be installed on-demand by customers of the Toolbox. | |
| projectdoc System Properties | Lists recognized system properties specified on the command line for starting the Confluence server. | Author, Documentation Architect, Documentation Gardener |
| Search Tips | Tips on specifying search queries for Lucene. This also applies to projectdoc's query macros. | Author, Documentation Architect |
| Space Properties | Lists the configuration options at space level. | Author, Documentation Architect, Documentation Gardener |
| Space Property Controls | Lists valid controls for properties to be used as space properties. | Author, Documentation Architect, Documentation Gardener |
| System Messages | Overview over system messages displayed in the browser or in a log file. | |
| Trouble Shooting | List of issues encountered with the projectdoc Toolbox and solutions or workarounds to resolve them. |
