Each VIVO document consists of a large number of wiki pages. These pages must work well together, both on the wiki and when exported to a PDF file. Here are some suggestions to help that happen.

Page sizes

Keep each page to a manageable size, and focused on a particular topic. If you find that the page is too complex or too diverse, break it into smaller pages. Within each group of pages, the parent should contain introductory material or an overview, while the child pages explore individual topics.

Start with a Table of Contents

Start the page with a call to the "Table of Contents" macro. The Table of Contents will include all of the headings in the current page. It will also include a top-level heading for each child page, thanks to the "Children Display" macro.

When the document is exported to a PDF file, the "Table of Contents" macros are not included. Instead, the file begins with a table of contents for the full document.

Follow with an Excerpt

If a page has a parent, the parent will show the child's excerpt text in its "Children Display" macro.

Confluence will only show the first sentence of an excerpt, so the excerpt should ideally be a one-sentence summary of the page.

Starting a page with a summary can seem odd. Enclosing the excerpt in a panel sets it off nicely from the main body of the page.

End with a Children Display macro

If a page has children, end the page with the "Children Display" macro. This will show the title of each child page, with its excerpt, and the next generation of pages as well. This combines with the excerpts on each page to provide easy navigation around the document.

Click on the "Children Display" macro to edit it, and set the options like this:

The macro will appear like this in edit mode:

And like this when the page is displayed.

When the document is exported to a PDF file, the "Children Display" macros are not included.

Use all heading levels

Sometimes it is tempting to use only level 1 headings and level 3 headings, for appearance. Try to avoid this. When the pages are combined into a PDF file, the heading levels will be restructured.

In the PDF file, the title of each child page becomes a level 1 heading. So if the Table of Contents in the PDF file shows three level 1 headings, they may be three child pages, or three actual headings within a single page, or any combination.

Headings within the child pages are demoted accordingly, to keep the organization intact. So a level 2 heading in the Table of Contents might represent:

• a level 2 heading in the parent page,
• a level 1 heading in a chile page,
• the title of a grandchild page.

Linking within the document

It's good to include links on the wiki pages, pointing to other areas of the document. However, these links will not be active in the PDF file. The text of the link should be sufficient to find its target.

When linking, don't link to a section number within the document. The section numbers are not available in the wiki pages, and a small change to the structure of the document could make the section numbers incorrect in the PDF.