Link

A link turns words into a way to somewhere else: another page in the wiki, a website, an email address, or a section further down the same page. Good links keep a page short. Instead of explaining again how to book a room, link to the page that already does.

Insert it

The dialog has two boxes. Address is where the link goes, and Display text is the words readers see and click. Fill in both and choose Save. If you leave Display text empty, the address itself is shown. Or choose + on the toolbar, then Link: with words selected, they become the display text.

• Keyboard: Ctrl+K (⌘+K on a Mac) opens the same dialog.

• Select some words and choose the link button in the small bar that appears above them. The words become the display text.

• Type or paste a web address into the text: it becomes a link when you type a space after it. Pasting an address while words are selected links those words.

You can leave out https://: Tesria adds it, so example.com works.

Kinds of link, and when to use each

A link in a sentence

Before you book travel, read the travel policy. It says which flights and hotels the company pays for.

The most common kind. Let the linked words say where the link goes, as part of the sentence. “Read the travel policy” tells a reader what they will get; “click here” does not, and neither does a long address.

A link to another page in this wiki

All six sizes of heading are shown on the Headings page.

Open the page you want, copy its address from the browser’s address bar, and paste it as the Address. The link keeps working when the page is renamed, because a page’s address does not change with its title.

A link to a section

Jump to Changing and removing a link further down, or to the six levels of heading on another page.

In the dialog, Headings on this page lists every heading on the page; choose one and its address fills in. Readers who click it are scrolled straight there. For a section of another page, add # and the heading’s address to the end of that page’s address: Headings explains how that address is made.

An email address or a phone number

Questions go to the help desk, or call +1 555 0100.

Type mailto: and the email address as the Address, such as mailto:help@example.com: clicking it opens the reader’s email app with a new message. tel: and a number does the same for calls, which is handy for anyone reading on a phone.

A bare address

The status page is at https://status.example.com.

When the address itself is what people need: to write down, read out, or type on another device. Otherwise, give the link words.

Changing and removing a link

While you edit, clicking a link does not follow it. It puts the cursor there and shows a small bar under it (on a phone, tap the link):

• The address opens the link in a new tab, so you can check where it goes.

• Edit opens the dialog as Edit link, to change the address, the words, or both, and Save. It also has Remove link.

• Remove takes the link away and keeps the words.

When a reader clicks a link, it opens in a new tab, so they keep their place on your page. A link to a heading on the same page scrolls there instead.

Good practice

• Link the words that describe the destination, not “here” or “this page”.

• Link a thing once, where it is first mentioned, not every time it comes up.

• Link rather than copy. When two pages need the same explanation, write it once and link to it, so there is only one copy to keep up to date.

• Check links to other websites now and then. Sites move things, and a link that goes nowhere costs readers trust.

Related elements

• Smart link shows a preview card of the page it points to: its title, picture and description.

• Headings give every section an address to link to.

• Table of contents links to every heading on a page at once.