Links, and links to hidden topics

Writing links

<xref href="install-cli.dita"/>                       <!-- another topic; text is its title -->
<xref href="preview.dita#preview/staff">the staff view</xref>   <!-- an element in a topic -->
<xref href="#links/hidden"/>                            <!-- an element in this topic -->
<xref keyref="env-vars">environment variables</xref>    <!-- through a key -->
<xref href="https://example.com" scope="external" format="html">Example</xref>

• An empty link shows the target topic's title as the reader sees it.
• Links to other local files, such as a sample YAML file, are served like images, only to readers who can see the linking topic.
• A link to a missing file, topic or element is an error, broken-link.
• External links may use http, https, mailto, tel or ftp, and external images http or https. Any other scheme, such as javascript: or data:, renders as plain text.
• related-links with link elements render as a "Related information" list. Links whose target is hidden are left out of it.

Links to hidden topics

Pages are shared by many readers, so a page often links to a topic some of its readers cannot see. For those readers, the link renders as its authored text, without the target's title and without a URL. A link with no authored text disappears.

So when a link's target may be hidden, give it link text that makes sense on its own, as the examples above do:

<!-- Good: reads well as plain text -->
<p>Operators set this in the <xref keyref="env-vars">server environment</xref>.</p>
<!-- Risky: an empty link vanishes for readers who can't see the target -->
<p>See <xref keyref="env-vars"/>.</p>

Or put the condition on the sentence that holds the link, so it disappears as a whole. For example, this sentence is only shown to readers with the embed product:

To open help in your own app, see Embed the help widget.

Links to topics outside the navigation

A topic that is in no navigation entry is never published, so links to it are plain text for everyone. Validation warns about them as link-to-unpublished. Add the topic to the site map, with toc="no" if it should not be listed.

In PDF publications, links to topics in the same publication jump within the PDF; links to other topics point at the docs site when the reader can see them there.