Creating links

What is a hyperlink?

Hyperlinks are one of the most exciting innovations the Web has to offer. They've been a feature of the Web since the beginning, and are what makes the Web a web. Hyperlinks allow us to link documents to other documents or resources, link to specific parts of documents, or make apps available at a web address. Almost any web content can be converted to a link so that when clicked or otherwise activated the web browser goes to another web address (URL).

For example, the BBC homepage contains many links that point not only to multiple news stories, but also different areas of the site (navigation functionality), login/registration pages (user tools), and more.

Anatomy of a link

A basic link is created by wrapping the text or other content inside an <a> element and using the href attribute, also known as a Hypertext Reference, or target, that contains the web address.

<p>
  I'm creating a link to
  <a href="https://www.mozilla.org/en-US/">the Mozilla homepage</a>.
</p>

This gives us the following result:

I'm creating a link to the Mozilla homepage.

Block level links

As mentioned before, almost any content can be made into a link, even block-level elements. If you want to make a heading element a link then wrap it in an anchor (<a>) element as shown in the following code snippet:

<a href="https://developer.mozilla.org/en-US/">
  <h1>MDN Web Docs</h1>
</a>
<p>
  Documenting web technologies, including CSS, HTML, and JavaScript, since 2005.
</p>

This turns the heading into a link:

Image links

To turn an image into a link, wrap the <img> element with an <a> element. The example below uses a relative path to reference a locally stored SVG image file.

img {
  height: 100px;
  width: 150px;
  border: 1px solid gray;
}

<a href="https://developer.mozilla.org/en-US/">
  <img src="mdn_logo.svg" alt="MDN Web Docs" />
</a>

This makes the MDN logo a link:

Adding supporting information with the title attribute

Another attribute you may want to add to your links is title. The title contains additional information about the link, such as which kind of information the page contains, or things to be aware of on the website.

<p>
  I'm creating a link to
  <a
    href="https://www.mozilla.org/en-US/"
    title="The best place to find more information about Mozilla's
          mission and how to contribute">
    the Mozilla homepage</a>.
</p>

This gives us the following result and hovering over the link displays the title as a tooltip:

Creating your own example links

OK, now it's your turn!

1. Click "Play" in the code block below to edit the example in the MDN Playground, or make a copy of our getting started template and copy the below code into there.
2. Link the "Red squirrel" and "Eastern gray squirrel" text to Wikipedia pages that describe the relevant species. Give each link a title attribute equal to the species' scientific name.
3. Link the "Wikipedia Squirrel page" text to the main Wikipedia page for squirrels.

If you make a mistake, you can clear your work using the Reset button in the MDN Playground. If you get really stuck, you can view the solution below the code block.

<h1>Squirrels</h1>

<p>
  Squirrels are commonly thought of as tree-dwelling mammals, but the squirrel
  family extends far beyond that to include ground-dwelling rodents such as
  chipmunks and prairie dogs, and flying squirrels.
</p>

<p>Two of the most common and best-known squirrel species are the:</p>

<ul>
  <li>Red squirrel</li>
  <li>Eastern gray squirrel</li>
</ul>

<p>
  For a good starting point on squirrel information, see the Wikipedia Squirrel
  page.
</p>

<h1>Squirrels</h1>

<p>
  Squirrels are commonly thought of as tree-dwelling mammals, but the squirrel
  family extends far beyond that to include ground-dwelling rodents such as
  chipmunks and prairie dogs, and flying squirrels.
</p>

<p>Two of the most common and best-known squirrel species are the:</p>

<ul>
  <li>
    <a
      href="https://en.wikipedia.org/wiki/Red_squirrel"
      title="Sciurus vulgaris">
      Red squirrel
    </a>
  </li>
  <li>
    <a
      href="https://en.wikipedia.org/wiki/Eastern_gray_squirrel"
      title="Sciurus carolinensis">
      Eastern gray squirrel
    </a>
  </li>
</ul>

<p>
  For a good starting point on squirrel information, see the
  <a href="https://en.wikipedia.org/wiki/Squirrel">Wikipedia Squirrel page</a>.
</p>

A quick primer on URLs and paths

To fully understand link targets, you need to understand URLs and file paths.

A URL, or Uniform Resource Locator, is a string of text that defines where something is located on the Web. For example, Mozilla's English homepage is located at https://www.mozilla.org/en-US/.

URLs use paths to find files. Paths specify where the file you're interested in is located in the website's filesystem. Let's look at an example of a website directory structure:

The root of this directory structure is called creating-hyperlinks. When working locally with a website, you'll have one directory that contains the entire site. Inside the root, we have an index.html file and a contacts.html. In a real website, index.html would be our home page or landing page (a web page that serves as the entry point for a website or a particular section of a website.).

There are also two directories inside our root — pdfs and projects. These each have a single file inside them — a PDF (project-brief.pdf) and an index.html file, respectively. Note that you can have multiple index.html files in one project, as long as they're in different filesystem locations. The second index.html would perhaps be the main landing page for project-related information.

Let's look at some examples of links between some different files in this directory structure to demonstrate different path types.

Same directory

If you want to include a hyperlink inside the top level index.html pointing to contacts.html, you can specify the path as just the filename that you want to link to, because it's in the same directory as the current file. The URL you would use is contacts.html:

<p>
  Want to contact a specific staff member? Find details on our
  <a href="contacts.html">contacts page</a>.
</p>

You can also start a path to a file inside the same directory using a single dot followed by a slash: ./. The following example is equivalent to the previous one, but some people like to include the ./ anyway because they feel it provides more clarity:

<p>
  Want to contact a specific staff member? Find details on our
  <a href="./contacts.html">contacts page</a>.
</p>

Moving down into subdirectories

If you want to include a hyperlink inside the top level index.html pointing to projects/index.html, you need to go down into the projects directory before indicating the file you want to link to. This is done by specifying the directory's name, then a forward slash, then the name of the file. The URL you can use is projects/index.html:

<p>Visit my <a href="projects/index.html">project homepage</a>.</p>

Moving back up into parent directories

If you want to include a hyperlink inside projects/index.html pointing to pdfs/project-brief.pdf, you have to go up a directory level, then back down into the pdfs directory. To go up a directory, you use two dots — .. — so the URL is ../pdfs/project-brief.pdf:

<p>A link to my <a href="../pdfs/project-brief.pdf">project brief</a>.</p>

Linking relative to the root directory

The above URLs work, but bear in mind that if you move either the linking file or the linked file to a different location, you will break the link.

If you want to create a link to a specific location that won't break if you move the linking file, you can do so by putting a single slash at the start of the path — this indicates that the path starts in the root directory of the site. For example, the previous link inside projects/index.html could be rewritten as:

<p>A link to my <a href="/pdfs/project-brief.pdf">project brief</a>.</p>

Now the path will always start from the root directory (creating-hyperlinks), travel to the pdfs directory, and find the project-brief.pdf file. This will still work if you move the linking file to a different location, for example a/b/c/d/e/index.html.

If you move the linked project-brief.pdf file to a different location, you will still break the link.

Document fragments

It's possible to link to a specific part of an HTML document, known as a document fragment, rather than just to the top of the document. To do this you first have to assign an id attribute to the element you want to link to. It normally makes sense to link to a specific heading, so this would look something like the following:

<h2 id="mailing_address">Mailing address</h2>

To link to that specific id, you include it at the end of the path, preceded by a hash/pound symbol (#), for example:

<p>
  Want to write us a letter? Use our
  <a href="contacts.html#mailing_address">mailing address</a>.
</p>

You can even use the document fragment reference on its own to link to another part of the current document:

<p>
  The <a href="mailing_address">company mailing address</a> can be found at the
  bottom of this page.
</p>

Absolute versus relative paths

Two terms you'll come across on the web are absolute path and relative path.

• Absolute path: Points to a location defined by its absolute location in your site (or elsewhere on the web). For example, you can create an absolute link that always points to the same location relative to the site root directory using the single slash at the start of the path, as we saw earlier: /pdfs/project-brief.pdf.
• Relative path: Points to a location that is relative to the file you are linking from. In our earlier example, we used projects/index.html to create a relative link between the current file and a file called index.html that is inside a projects subdirectory. If you were to move the current file to a different location, the path would still be relative to that file, but it would point to a different absolute location.

How do paths translate into URLs?

When talking about static websites, the URL a file is available at is a combination of the location it is uploaded to on a web server, and the domain name of the website.

For example, if we upload our sample site directory structure to the root of a web server (not in some kind of subfolder) and the website domain name is set to example.com, our pdfs/project-brief.pdf file would be available at https://www.example.com/pdfs/project-brief.pdf.

If we wanted to create a working link to this file:

• /pdfs/project-brief.pdf would always create a link to https://www.example.com/pdfs/project-brief.pdf, as it is an absolute path that always points to the same place on the site.
• projects/index.html would create a link to https://www.example.com/projects/index.html, but only when included in a file inside the root directory, such as the top-level index.html file, or contacts.html. If you included it, for example, inside an HTML file at pdfs/index.html, it would link to https://www.example.com/pdfs/projects/index.html, which doesn't exist, so you'd end up with a broken link.

The default index.html page

When referencing an index.html file, you generally don't need to include the index.html in the URL/path, because web servers look for a default landing page called index.html when a filename isn't specified.

Looking again at our projects/index.html path example, we could just write the path as projects, and this would create a link to https://www.example.com/projects/index.html. When navigating to the page, we could write the URL as https://www.example.com/projects/ and it would still get us to the right place.

Specifying a URL as the path

You can specify a full URL as your path, which will always point to the same location on the web, no matter where it's used. For example:

<a href="https://www.example.com/projects/">projects</a>

This link will always link to https://www.example.com/projects/, no matter where it appears in a site. In this context, the URL is a type of absolute path.

Internal versus external links

When a link points to a resource on your site, it is referred to as an internal link. When a link points to a resource on a different site, it is called an external link.

When specifying an external link, you always have to include the full URL as the path, for example:

<a href="https://www.some-other-site.com">projects</a>

You can't reference a location on a different site with a path like /pdfs/project-brief.pdf or projects/index.html, as they are both relative to a location on your own site, and the browser needs the website's domain name to be able to find it.

When specifying an internal link, you can use a relative or absolute path, or a full URL. In our example, these links are equivalent:

<a href="https://www.example.com/projects/">projects</a>

<a href="projects">projects</a>

However, there are a couple of good reasons why you shouldn't use full URLs for internal links:

• Efficiency: It takes more resources to look up a full URL. If you specify https://www.example.com/projects/, when a user clicks on the link the browser will first look up the server location, then look for the linked page. If you specify projects, the browser will immediately look for the linked page on the same server it is already on.
• Portability: As we've said before, if you specify https://www.example.com/projects/, it will always link to https://www.example.com/projects/. If you then move your website to a different domain, for example another-example.com, your full URL links will all need to be changed. If you specify paths such as projects, they will still work, as they are still relative to the directory structure.

Link best practices

There are some best practices to follow when writing links. Let's look at these now.

Use clear link wording

It's easy to throw links up on your page. That's not enough. We need to make our links accessible to all readers, regardless of their current context and which tools they prefer. For example:

• Screen reader users like jumping around from link to link on the page, and reading links out of context.
• Search engines use link text to index target files, so it is a good idea to include keywords in your link text to effectively describe what is being linked to.
• Visual readers skim over the page rather than reading every word, and their eyes will be drawn to page features that stand out, like links. They will find descriptive link text useful.

Let's look at a specific example:

Good link text: Download Firefox

<p><a href="https://www.firefox.com/en-US/">Download Firefox</a></p>

Bad link text: Click here to download Firefox

<p>
  <a href="https://www.firefox.com/en-US/">Click here</a> to download Firefox
</p>

Other tips:

• Don't repeat the URL as part of the link text — URLs look ugly, and sound even uglier when a screen reader reads them out letter by letter.
• Don't say "link" or "links to" in the link text — it's just noise. Screen readers tell people there's a link. Visual users will also know there's a link, because links are generally styled in a different color and underlined (this convention generally shouldn't be broken, as users are used to it).
• Keep your link text as short as possible — this is helpful because screen readers need to interpret the entire link text.
• Minimize instances where multiple copies of the same text are linked to different places. This can cause problems for screen reader users, if there's a list of links out of context that are labeled "click here", "click here", "click here".

Linking to non-HTML resources — leave clear signposts

When linking to a resource that will not be opened in the current page as a "normal navigation", you should add clear wording to the link text about what is going to happen. For example, if you're downloading or streaming a resource, or if the link is going to open a popup or perform some other potentially unexpected effect, this should be stated in the text. This is important for users on low bandwidth connections, who might want to avoid downloading assets of multiple megabytes. It also helps to set up expectations for screen reader users, who may not be aware of what's happening otherwise.

Let's look at some examples, to see what kind of text can be used here:

<p>
  <a href="/large-report.pdf" download>
    Download the sales report (PDF, 10MB)
  </a>
</p>

<p>
  <a href="https://www.example.com/video-stream/" target="_blank">
    Watch the video (stream opens in separate tab, HD quality)
  </a>
</p>

Use the download attribute when linking to a download

When you are linking to a resource that's to be downloaded rather than opened in the browser, you can use the download attribute to provide a default save filename. Here's an example with a download link to the latest Windows version of Firefox:

<a
  href="https://download.mozilla.org/?product=firefox-latest-ssl&os=win64&lang=en-US"
  download="firefox-latest-64bit-installer.exe">
  Download Latest Firefox for Windows (64-bit) (English, US)
</a>

When to open links in a new tab

Links by default open in the same tab as the page they are on, which allows the user to navigate back to the previous page using the browser's back button. However, many sites (including MDN) choose to open certain links, especially external links, in a new tab. This is done by setting the target attribute to "_blank".

Firefox is developed by the
<a href="https://www.mozilla.org/en-US/" target="_blank">Mozilla Foundation</a>.

Whether or not to open links in a new tab should be a conscious decision, based on user experience design considerations. Here are some things to think about:

• Opening links in a new tab presents the two documents simultaneously, which is useful for a "parallel" navigation experience. On the other hand, links that open in the same tab are more like a continuation of the current page.
• Opening links in a new tab can be disorienting for users who are accustomed to using the back button.
• Even when links are opened in the same tab by default, users can still choose to open them in a new tab, using keyboard shortcuts or context menu options. On the other hand, links that open in a new tab are hard to open in the same tab.
• Screen reader users may be confused by links that open in a new tab, as they may not realize that the new tab has opened, and they may lose context about their location on the page.

A common approach is to open external links in new tabs and internal links in the same tab. Some designers prefer to open all links in the same tab. If you do open links in new tabs, then it is recommended that you provide cues for these links, such as an icon next to the link text.

Creating a navigation menu

For this exercise, we'd like you to link some pages together with a navigation menu to create a multipage website. This is one common way in which a website is created — the same page structure is used on every page, including the same navigation menu, so when links are clicked it gives the impression that you are staying in the same place, and different content is being brought up.

You'll need to make local copies of the following four pages, all in the same directory. For a complete file list, see the navigation-menu-start directory:

• index.html
• projects.html
• pictures.html
• social.html

You should:

1. Add an unordered list in the indicated place on one page that includes the names of the pages to link to. A navigation menu is usually just a list of links, so this is semantically OK.
2. Change each page name into a link to that page.
3. Copy the navigation menu across to each page.
4. On each page, remove just the link to that same page — it's confusing and unnecessary for a page to include a link to itself. And, the lack of a link acts a good visual reminder of which page you are currently on.

The finished example should look similar to the following page:

Email links

It's possible to create links or buttons that, when clicked, open a new outgoing email message rather than linking to a resource or page. This is done using the <a> element and the mailto: URL scheme.

In its most basic and commonly used form, a mailto: link indicates the email address of the intended recipient. For example:

<a href="mailto:nowhere@mozilla.org">Send email to nowhere</a>

This results in a link that looks like this: Send email to nowhere.

In fact, the email address is optional. If you omit it and your href is "mailto:", a new outgoing email window will be opened by the user's email client with no destination address. This is often useful as "Share" links that users can click to send an email to an address of their choosing.

Specifying details

In addition to the email address, you can provide other information. In fact, any standard mail header fields can be added to the mailto URL you provide. The most commonly used of these are "subject", "cc", and "body" (which is not a true header field, but allows you to specify a short content message for the new email). Each field and its value is specified as a query term.

Here's an example that includes a cc, bcc, subject and body:

<a
  href="mailto:nowhere@mozilla.org?cc=name2@rapidtables.com&bcc=name3@rapidtables.com&subject=The%20subject%20of%20the%20email&body=The%20body%20of%20the%20email">
  Send mail with cc, bcc, subject and body
</a>

Here are a few other sample mailto URLs:

• mailto:
• mailto:nowhere@mozilla.org
• mailto:nowhere@mozilla.org,nobody@mozilla.org
• mailto:nowhere@mozilla.org?cc=nobody@mozilla.org
• mailto:nowhere@mozilla.org?cc=nobody@mozilla.org&subject=This%20is%20the%20subject

Summary

That's it for links, for now anyway! You'll return to links later on in the course when you start to look at styling them. Next up, we'll give you some tests that you can use to check how well you've understood and retained the information we've provided on links.

• Previous
• Overview: Structuring content with HTML
• Next