Confluence features for Organizing Pages
Features for managing and setting site and page structure
- Hierarchy: A pages is always created as a child of some other page, and can be moved to different parent as needed. This does not impact URL.
- Child order: Children of a particular parent page can be set to a particular order. This primarily affects the order in which they will be displayed (See comments below on children and on "next" or "previous".)
- Within page: Headings: Within a page, headings h1..h6 show some visual hierarchy of topics. (This is used by one or more TOC macros... see below).
- There's no enforcement the heading hx levels must be properly nested, and in fact it may be common to select hx markup based on appearance -- there may be too little distinction between h2 and h3 for instance, prompting user to set h4 as a subsection of an h2 section.
- Include mechanism: Pages can use the "include" macro to insert the entire contents of another page (minus title). This allows
- building pages from standard blocks
- using the same content stand-alone or in assembled into one or more"compendium" pages.
- PDF: One use for compendium pages is to create "printable" docs, which overlaps with the topic of creating PDF versions of wiki page collections. Confluence's built-in PDF gen is a work-in-progress. I got better results from using Firefox to print to Adobe PDF (ie: Acrobat functionality.) More paper-suitable font size, and fewer instances of messed-up formatting.
- Excerpt mechanism: The "excerpt" and "excerpt-include" macros can be used to define a subsection of a page for inclusion in another page. Usually used for displaying page summaries in lists of pages.
Features for displaying structure
- toc: Page Table of Contents: The toc macro inserts a hierarchical TOC tree-of-links of the entire current page, based on its headings, h1..down to settable hx level. The toc-zone macro allows delimiting a section of a page, and inserts a TOC of that section at top or bottom of the section.
- Works with include-d content: These macros are applied after includes, hence work on the included content.
- Filter: Can filter out some headings based on include and exclude macro arguments.
- children: List children of a page: The children macro lists children of a particular page (defaulting to the current page), in a hierarchical tree-of-links.
- Default order is alphabetical by title, however manual ordering overrides this.
- Manual page order remembered? The page-order mechanism (accessed in List Pages -- Tree View) seems to remember the manual ordering and return to it after selecting alpha order. Whichever order was last selected is what the next user to view the TOC will see.
- Manual order is fragile due to ease with which alpha order can be reinstated.
- New pages? Where does a page newly added to a parent get positioned within an existing manual sort order? Not clear.
- No Filter: Unfortunately, does not have filter capability.
- Convenient link and anchor syntax defaults:
- Anchors: Confluence automatically creates anchors for headings. No syntax necessary!
- Links: Uses square brackets, in this pattern (shown here with parens to avoid interpretation): (Visible caption|Link name), or (Visible caption|#Anchor name). But if the visible caption should be the same as the anchor name, then this syntax works: (#Anchor name).
- Page breaks: For page breaks in print-outs, use the html macro and insert page break div:
- (html) <DIV mce_style="page-break-before: always;" style="page-break-before: always;"></DIV>(html)
- NOTE: In (html) replace the parens with curly braces
Issues
- Page Hierarchy vs Topic groups: Often one wants to wind up with a TOC where certain nodes are not pages but are instead topic headings for a collection of subsidiary pages pertaining to that particular topic. This can be partly achieved by adding a dummy page whose only purpose is to provide that topic heading (and then moving the pertinent subsidiary pages under that dummy parent). This works, but (a) introduces superfluous pages that must be maintained, and (b) in the TOC causes there to be not just topic headings but links to the dummy pages.
- TOC Indent level for include scenarios: The toc macro makes no distinction between content written in the current page vs content included. But this means that there's no way to make the toc entries of included pages appear subsidiary to the toc entries of the host page.
- Actually, the "real problem" is that, unsurprisingly, the header h-levels of the included pages themselves are not adjusted to be relative to the including page. Then toc would just work. Without this feaure, this pretty much means that tocs for pages assembled with "include" have to be maintained manually.
- Child ordering and Next/Previous: There's no out-of-the-box macro for next/previous navigation, though there might be one or more 3rd party one.
- Navigation plugin: OK, but looks kind of old, and it's based on alpha page ordering I think
- Page Title changes: When a page title is changed, macro invocations where that page title is referenced are not updated, and hence no longer work
- Proper Outline management: There's a string argument for management of long documents (or collections of wiki pages that form a coherent whole) to be separated from the pages themselves. Thisoutline pluginappears to be the right kind of idea, but is only in prototype state.
Confluence Feature and Documentation links
- Notation Guide (in wiki itself)
- Working with Macros Includes list of all supplied macros, and some others.
- children macro Inserts a tree list of the titles/link of the pages which are children of a particular page (by default the current page) . Settable depth.
- excerpt macro Marks off a section of page which can then be included in another page using exerpt-include macro.
- include macro Includes another page into the current one. Omits the other page's title.
- User Macros: List of available User Macros (not necessarily installed)
- Plugins index: List of available Plugins (not necessarily installed)
- Confluence TOC plugin
- At Customware
- toc and toc-zone macros. Apparently can only create TOC for current page, not other page. toc-zone can mark off a section of a page and place within it (at top or bottom) a TOC of just thatsection.
- Composition plugin
Labels:
None