Set a Link

The Wiki Link Macro allows to control the rendering of links. Dependent on the existence of the target document, the link may be rendered differently, for instance empty or as plain text (without a link).

The reason to render a link to empty could be to not render a reference to an document that does not exist. If you choose to render the label as text, readers would anticipate correctly where a link would be rendered as soon as the referenced document comes into existence. These are simply different rendering strategies for different use cases.

Set Links in a List

If you have such a link (using the Wiki Link Macro) in bullet list and choose to render a link to a not-yet existing page as empty, there will be a noisy empty bullet point. You could render the link as plain text, which may provide some guidance to users. It can indicate that a piece of information may exist in the future and that here will be the location of a link to this piece of information.

Doctype add-ons use this approach frequently on space homepages.

Above you see five bullet points, each has a Wiki Link Macro, but only three of them point to existing documents (Profiles, Tours, and Topics). FAQs (rendered as plain text) and Glossary (the last list item which is rendered as empty) point to documents that do not exist.

Discard Lines

To get rid of unwanted lines in a list of items, the Table Merger Macro – despite of its name – is a handy tool. Wrap the list within the body of the macro.

In order to remove the empty line at the end of the list in the example above set the Discard parameter to empty.

The result on discarding empty lines is that the last item is removed:

Discarding empty lines and lines without links by selecting no-links results in removing the FAQs and the Glossary link:

For Template Authors

In case you design templates use the Wiki Link and Table Merge Macro like this:

<ac:structured-macro ac:name="projectdoc-table-merger-macro">
  <ac:parameter ac:name="discard">no-links</ac:parameter>
  <ac:rich-text-body>
    <ul>
      <li>
        <ac:structured-macro ac:name="projectdoc-link-wiki">
          <ac:parameter ac:name="page">projectdoc.content.profile.home.title</ac:parameter>
        </ac:structured-macro>
      </li>
      <li>
        <ac:structured-macro ac:name="projectdoc-link-wiki">
          <ac:parameter ac:name="page">projectdoc.content.tour.home.title</ac:parameter>
        </ac:structured-macro>
      </li>
      <li>
        <ac:structured-macro ac:name="projectdoc-link-wiki">
          <ac:parameter ac:name="page">projectdoc.content.faq.home.title</ac:parameter>
        </ac:structured-macro>
      </li>
      <li>
        <ac:structured-macro ac:name="projectdoc-link-wiki">
          <ac:parameter ac:name="page">projectdoc.content.topic.home.title</ac:parameter>
        </ac:structured-macro>
      </li>
      <li>
        <ac:structured-macro ac:name="projectdoc-link-wiki">
          <ac:parameter ac:name="empty-handling">empty</ac:parameter>
          <ac:parameter ac:name="page">projectdoc.content.glossary-item.home.title</ac:parameter>
        </ac:structured-macro>
      </li>
    </ul>
  </ac:rich-text-body>
</ac:structured-macro>

Summary

This short tip has shown how to manually construct lists with line items to be rendered or not at request time.

The combination of the Wiki Link Macro and the Table Merger Macro supports template authors to manually construct navigation links in lists.

Resources