Create Links

You have many options for adding links to your site. You can link to an internal page, an another website, you can create email links and link to internal documents or files on a service like Google Drive.

This guide covers how to add links in a text area, like the Text Area Paragraph or a Body field, and best practices for naming links.

Automatic links

Anything that has the format of a URL (https://....) or an email address (with an @ symbol) will be automatically linked by the text editor. For all other cases, see below.

Add links to text

Here's how to add the text to a link:

1. Select the text you would like included in the link.
2. Click on the Link button in the Text Area toolbar to open the Add Link tool.
3. In the URL field you can:
   • To link to a page on your site or a file you have uploaded, start typing the name of page or file. Then select from the list.
   • To link to an another website, enter the entire URL, starting with "https://"
4. Press tab to the green check mark and then enter or click the green check mark to save
5. Verify your link works as expected.

To link to an existing page on the site, type the name of the page into the "Link URL" field. A list of suggestions will display below the input field. Click on the page you wish to link to and then click the green check mark.

Update a link

If you need to change the destination for a link, click on the link in the text editor. This will bring up the link toolbar. Click on the pencil icon. 

You can then start to type a new page title or enter an external URL. When you are done click the green checkmark.

Add links to email addresses 

As mentioned earlier, anything that looks like an email address will automatically become a mailto: link.

Email ("mailto") links can be added to text within text areas, as well as other paragraphs. Email links will be displayed with an email icon that is added automatically. For example:

Report phishing

1. Highlight the text area you would like included in the email link.
2. Click on the Link button in the Text Area toolbar to open the Add Link modal.
3. In the URL field, add "mailto:" followed by the email you would like to link to. For example: mailto:spam@stanford.edu
4. Click Save.

Link to documents

You can link to documents such as PDFs and Word documents from your site. If you have a large quantity of documents, we recommend hosting them externally on Google Drive for storing and managing them. However, you can also upload and store documents directly on your site using the Media Library. For instructions on adding documents to your media library, see Adding a file. When documents are stored on your site they will be available for accessibility scanning by Siteimprove. 

When creating a link, you'll want to let the user know what to expect. When linking to a document you'll want to let the user know the type of document and size. We suggest providing the document name, type, and size as follows:
[name] ([document type], [size]).

For example: Sample document (PDF, 1MB)

Embed documents (files) from the Media Library

When you upload a document to your site, you can add a simple link to it in the text editor. Using this approach will display the filename and size of the document, and will appear as:

samplepdf.pdf (28.37 KB)

1. Place your cursor where you'd like the link to appear
2. Click on the Media Library button

3. Select media type File

   
4. Either upload a new file or select an existing file. 

5. Save and insert the file.

   

Link to documents in the Media Library

1. Highlight the text area you would like included in the link.

2. Click on the Link button in the Text Area toolbar to open the Add Link modal.

   

3. In the URL field, start typing the Media Name for the document you are trying to link to. Suggestions of documents will appear as you continue to type.

   

    

4. Once your desired document appears, select it.
5. Click Save, and your link should appear as follows:

Sample (PDF, 30KB) 

Link to external documents

When linking to a document hosted externally, it is linked to as a URL and not as a media file.

To Link to a file in Google Drive or Box:

1. Navigate to the file
2. Copy the URL
3. Add the link using the steps in the section above entitled Adding links to text within a text area

Write accessible link text

Explain where your link is going

It's been a common practice to introduce something, such as a news item, and provide a link to the full story with generic link text that says "Read more." However, with multiple links on a page that all say "Read More", it becomes problematic for people using assistive technology. Links are used to guide people through your website or to content hosted elsewhere, and encourage your users to take specific actions.

For example, when using cards to direct readers to related content, you might be tempted to use "Read more" on each card. 

Depending on the context, this will cause Siteimprove to flag the following issues:

• Siteimprove issue: Do these links (in the same context) go to the same page?, and violates WCAG 2.1: Understanding Success Criterion 2.4.4: Link Purpose (In Context), or 
• Siteimprove issue: Are these links identical? and violates WCAG 2.1: Understanding SC 2.4.9: Link Purpose (Link Only) 

When a screen reader encounters these links, they read the same. The image below displays the information VoiceOver provides for those links. It will sound to the listener like this: "Link, Read more. Link, Read more, Link, Read more." 

Rules of writing accessible link text

When writing link text:

• Make it a call to action by starting with a verb. People are far less likely to click on a link that is a noun, they want to be led through your site. Rather than “About us,” try “Read about our team.”
• If the links go to different pages, for each link, the link text is different.
• If the links go to the same page, the link text must be the same for each page.

Fixing "Read more" links

Here are some examples of how you might fix the link text:

Related content

Learn more about writing descriptive text for links from ODA

Differentiating "Read more" links with aria-label

This is an advanced approach, requires modifying the underlying HTML, and is not recommended.

This allows you to keep the "Read more" text but makes the links accessible to screen readers and other assistive technology by modifying the underlying HTML. In this approach, you will differentiate links using the aria-label attribute. The title attribute is optional; it allows mouse users access to the same content. Note that the content is not available on a touch screen, which means mobile users will not see this content. 

To do this you'll need to modify the source code directly. For example:

<a href="/home" 
  title="The Target. This uniquely describes the target" 
  aria-label="The Target. This uniquely describes the target"> 
  The Target 
</a>

Important: The text in the aria-label must contain the visible text. In this example the visible text is "The Target", therefore, the text in the aria-label must contain the words "The Target". It is best if you can begin the text contained in aria-label with the visible text. 

Here is the link in action:

The Target 

For cards

When creating a "Read more" link in a card, you will need to:

1. Move the link from the link field to the description text field instead.
2. Modify the source code in the description text field to add the necessary aria-label and title attributes.

Here's an example of the underlying HTML for a "Read more" link:

<a href="https://sitesuserguide.stanford.edu/home" 
  aria-label="Read more about example link one" 
  title="Read more about example link one"> 
  Read more
</a>

For publications

Industry standard for publications often dictates how inline link references display. The problem is that with this standard, the link text to two different locations on the same site will look the same. This violates WCAG 2.1: Understanding Success Criterion 2.4.4: Link Purpose (In Context). 

Here's how this might be used for publications:

Etiam ultricies nisi vel augue. ( NCES, 2020 ).  Donec elit libero, sodales nec, volutpat a, suscipit non, turpis. ( NCES, 2020 ).

Tips

Adding a link to the homepage (front page) of your site

In the WYSIWYG editor, to link to the home page just use a forward slash, i.e., /. 

Adding a link using shortcuts

Keyboard shortcuts can also be used to add a link. For Mac, the shortcut is "command" plus "K", and for PC, the shortcut is "Ctrl" plus "K" (Chrome recommended). Using these shortcuts will open up a link modal. This keyboard shortcut can also be used to modify existing links.

1. Highlight the text area you would like included in the link.
2. Type the keyboard shortcut (Mac: "command" plus "K", PC: "Ctrl" "K") to open the Link modal.
3. Add the URL
4. Click Save.

Troubleshooting Links

How do I remove email links if they are displayed unintentionally?

In a few use cases, an email link (with mail icon) may unintentionally appear on non-linked text after the page is saved. For example, this can occur for some code snippets or examples that include the @ sign. In these situations, you can remove the email link and icon by wrapping the text in a <code> tag.

1. Within the Text Area WYSIWYG toolbar, Click Source to display your Text Area as HTML.
2. Find the text that is unintentionally displaying the email link, and wrap it with an opening <code> tag and a closing </code> tag.