HTML href Examples: Linking Pages, Files, and URLs

The href attribute tells HTML where a link points. On an <a> element it creates a hyperlink; on a <link> element it associates a related resource such as a stylesheet. Use a complete URL for an external destination and a relative reference for a page or file whose location is resolved from the current document’s base URL.

The HTML Standard defines an anchor with href as a hyperlink labeled by its contents. WHATWG HTML Standard

Basic href examples

<!-- External page: complete URL -->
<a href="https://developer.mozilla.org/">MDN Web Docs</a>

<!-- Same site, root-relative path -->
<a href="/help/contact.html">Contact support</a>

<!-- Relative to the current document -->
<a href="guide.html">Read the guide</a>

<!-- Parent directory -->
<a href="../index.html">Back to the parent page</a>

<!-- Section in this document -->
<a href="#installation">Jump to installation</a>

<h2 id="installation">Installation</h2>

Write link text that explains the destination or action. “Download the project brief (PDF)” is clearer than “click here.” See MDN’s <a> reference for destination types and authoring guidance.

Absolute, root-relative, and directory-relative URLs

Href value	How it resolves	Typical use
`https://example.com/about`	Names scheme, host, path, and optional query or fragment	External sites or a URL that must be explicit
`/help/contact.html`	Starts at the current site’s origin	Stable links within your own site
`guide.html`	Relative to the current document URL	Sibling pages in the same directory
`../index.html`	Moves up one path segment, then resolves	Links from a nested directory to its parent
`#installation`	Stays on the current resource and selects an element ID	Table of contents and in-page navigation

How the browser resolves a relative href

Suppose the current page is https://www.example.com/docs/start.html:

guide.html becomes https://www.example.com/docs/guide.html.
../index.html becomes https://www.example.com/index.html.
/about becomes https://www.example.com/about.
#options keeps the page URL and targets id="options".

A path such as example.html is not the same as https://www.example.com/example. The first depends on the current base URL and names a file-like path; the second is a complete URL that does not need the current page for resolution. MDN explains these distinctions in Creating links.

Linking pages on the same site

<nav aria-label="Primary">
  <a href="/">Home</a>
  <a href="/docs/">Documentation</a>
  <a href="/pricing">Pricing</a>
</nav>

Root-relative links such as /docs/ remain correct when the current page moves between directories. Directory-relative links are convenient for small, self-contained folders but can break after a file is relocated.

Linking files such as PDFs and downloads

<a href="/files/project-brief.pdf">Download the project brief (PDF)</a>
<a href="/assets/report.csv">Open the CSV report</a>

The server’s response headers and the browser determine whether a file opens inline or downloads. Do not promise a download solely because the URL ends in a file extension. Make the link text describe the file and outcome.

Linking a location on the same page

<ol>
  <li><a href="#href-on-a-vs-link">Anchor versus link</a></li>
  <li><a href="#troubleshooting">Troubleshooting</a></li>
</ol>

<h2 id="href-on-a-vs-link">Anchor versus link</h2>
<h2 id="troubleshooting">Troubleshooting</h2>

The fragment after # must match an element’s id. IDs should be unique in the document. href="#" and href="#top" are commonly used for top-of-page links when a matching target exists.

Email and telephone href schemes

<a href="mailto:hello@example.com">Email hello@example.com</a>
<a href="tel:+123456789">Call +1 234 567 89</a>

mailto: asks the device to open a configured email application. tel: asks it to open a calling application. Behavior depends on the user’s device and installed software; these schemes do not guarantee that a message is sent or a call is placed.

href on `<a>` versus `<link>`

Element	Purpose	Example
`<a href>`	Creates a navigational or actionable hyperlink for readers	`<a href="/about">About</a>`
`<link href>`	Associates the document with a resource; `rel` states the relationship	`<link rel="stylesheet" href="/css/site.css">`

<head>
  <link rel="stylesheet" href="/css/site.css">
</head>

Read MDN’s <link> reference for resource-link behavior.

Base URLs and the `<base>` element

<head>
  <base href="https://www.example.com/docs/">
</head>
<a href="guide.html">Guide</a>
<img src="images/diagram.svg" alt="Architecture diagram">

With this base, guide.html resolves to https://www.example.com/docs/guide.html, regardless of the document’s own URL. A <base> can change every relative href, src, and similar reference, so add it deliberately and verify navigation after introducing it. See MDN’s <base> reference.

Query strings, fragments, and URL encoding

<a href="/search?q=html%20href&sort=recent">Search recent HTML results</a>
<a href="/docs/page.html?lang=en#examples">English examples</a>

Use URL encoding for spaces and reserved characters in query values. In HTML source, write an ampersand as &. The browser sends the decoded URL semantics after parsing the attribute.

Reliable href checklist

Choose a full URL for an external site or an address that must be explicit.
Choose /path for a same-origin route independent of the current directory.
Choose page.html or ../page.html when the relationship to the current directory is intentional.
Match fragment links to unique, stable id values.
Use descriptive anchor text that tells readers what they will open or do.
Check links after moving files, changing routing, or adding a <base> element.
Encode query parameters and escape ampersands in HTML.

Troubleshooting href problems

Symptom	Likely cause	Fix
Link opens the wrong directory	A directory-relative path was resolved from an unexpected page URL	Inspect the current URL; use a root-relative path such as `/docs/guide.html` when appropriate.
Fragment link does nothing	No matching `id`, a typo, or duplicate IDs	Make the target ID exact and unique.
Stylesheet does not load	Incorrect `<link>` path or a `<base>` changed resolution	Resolve the URL against the document/base URL and inspect the browser network panel.
External link goes to your own site	The scheme or host was omitted	Use `https://host/path` for an external destination.
Query string is malformed	Unencoded spaces or unescaped `&` in HTML	Percent-encode values and write separators as `&`.
PDF opens instead of downloading	Server response headers or browser policy	Describe the result accurately; configure server download headers if you control the response.

Performance, reliability, and maintenance

Relative URLs are compact and can survive a domain change, while absolute URLs make the destination unambiguous and are required for many external references. Root-relative URLs reduce directory mistakes on the same origin. For large sites, generate links from your router or build system, run a broken-link checker in CI, and test pages with a base URL if your deployment uses one. Keep fragment IDs stable when other pages or bookmarks depend on them.

Or skip the browser setup

If your goal is to document or monitor how an href target renders, ScreenshotNeo captures a clean image or PDF with one request. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server gives AI agents tools named take_screenshot, get_page_info, and capture_pdf.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for the full option set. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Should internal links use a full URL?

Usually no. Use a root-relative or directory-relative path when the destination is on the same site. Use a full URL when the complete address must be explicit or the destination is external.

Does an anchor need href?

An <a> without href is not a hyperlink. Add href for navigation or use another appropriate interactive element for an action.

Can href point to an email address or phone number?

Yes. Use mailto: and tel:; the device decides which application handles them.

What changes when I add a base element?

All relative references resolve against the base URL instead of the document URL. Recheck every relative link and resource after adding it.