Anchor Link: What It Is and How to Use It in HTML

What is an anchor link, and how do you add one to a web page? An anchor link points to a specific location on the same page or on another page. HTML connects the clickable link to an element with a matching id value, so the browser can open the page at that location.

<a href="#installation">Installation</a>

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

The <a> element is the link. “Installation” is its visible anchor text. The href contains the URL fragment, and id="installation" marks the destination. Browsers process the fragment after loading the document, then scroll to the matching element. The fragment is not sent to the server, as documented by MDN’s URI fragment reference.

What is an anchor link?

An anchor link creates a shortcut to a named position in a document. A same-page anchor link uses a fragment such as #installation. A link to another page combines a path and fragment, such as /guides/setup#installation.

A regular internal link usually takes a reader to the beginning of another URL. An anchor link takes the reader to a particular section. Both use the HTML anchor element and an href attribute. The destination changes the behavior.

For example, a documentation page might contain a table of contents near the top. Selecting “Configuration” changes the URL to /docs/tool#configuration and moves the viewport to the element with id="configuration". The browser does not need a JavaScript click handler for this behavior.

An anchor link works only when its fragment matches a unique destination ID in the rendered document.

Anchor text also carries meaning. “Read the installation steps” tells a visitor what follows. “Click here” does not. The W3C recommends link text that describes a link’s purpose, especially for people who navigate with screen readers. Google’s link guidance likewise describes anchor text as information about the destination.

How to create an anchor link in HTML

Start with the target, then add the link. The target can be a heading, a paragraph, a form, or another suitable element. A heading is usually the clearest choice because it gives the destination a visible label and preserves the document structure.

Same-page links

<nav aria-label="On this page">
  <a href="#requirements">View requirements</a>
</nav>

<h2 id="requirements">Requirements</h2>
<p>Install Node.js before running the build command.</p>

The fragment begins with #. It must match the target ID exactly. HTML IDs are case-sensitive in fragment matching in common browser behavior, so lowercase IDs reduce avoidable mistakes.

Links to another page

<a href="/guides/deployment#rollback">Read the rollback procedure</a>

The browser first requests /guides/deployment, then looks for id="rollback". If the target does not exist, the page may load normally but the browser cannot scroll to the requested location.

Use stable IDs made from lowercase words and hyphens. Prefer id="api-authentication" over id="API Authentication". Keep every ID unique within the page. Avoid changing a published ID casually because bookmarks, documentation links, search results, and links from other sites can depend on it.

Part	Example	Purpose
Link element	<a>	Creates the interactive link
Anchor text	View requirements	Explains the destination to readers
Fragment	#requirements	Names the location in the URL
Destination ID	id="requirements"	Marks the location in the document

Where anchor links are useful

Use an anchor link when a reader needs a precise answer inside a longer page. A good fragment reduces scrolling, gives documentation a usable table of contents, and lets another page point directly to the relevant explanation.

• Documentation: Link “Authentication,” “Environment variables,” and “Troubleshooting” from an on-page navigation list.
• Long guides: Let readers jump to prerequisites, setup, examples, or deployment steps.
• Comparison pages: Link to a specific pricing, feature, or integration section when the page contains several decisions.
• Articles: Point a reader directly to a definition or implementation example.
• Skip links: Add a keyboard-accessible link such as href="#main-content" before navigation, with a matching main landmark.

Accessibility depends on more than the fragment. Use descriptive link text, keep headings in a logical order, and make the target visible after navigation. A fixed header can cover the heading after the browser scrolls. CSS such as scroll-margin-top on headings can create room for that header.

h2,
h3 {
  scroll-margin-top: 5rem;
}

Do not use anchor links to hide poor organization. If readers need a complete explanation of API authentication, that topic may deserve its own page rather than a buried section in a general guide. A fragment is a navigation aid, not a replacement for clear information architecture.

Anchor links and internal linking

Internal linking connects pages within one site. An anchor link can add a second layer by identifying a section inside the destination page. These mechanisms solve different problems.

Link type	Example	Use it when
Page link	/guides/technical-seo	The destination is a standalone topic
Same-page fragment	#audit-checklist	The reader needs a section on the current page
Cross-page fragment	/guides/seo#audit-checklist	A specific section answers the reader’s question

For a site about coding-agent SEO, a page explaining technical SEO deserves its own URL. A link from that page to #audit-checklist helps a developer reach the working list without pretending the list is a separate topic. Google can crawl ordinary HTML links with an href; script-only navigation and empty anchors create weaker signals, according to Google Search Central’s link guidance.

An automatic internal linking workflow can inspect related pages and suggest links, but a fragment still needs a real target in the source. SEOAgent fits a repository-based workflow: the user’s own model runs inside a coding agent such as Claude Code, Cursor, or Codex; the agent proposes edits to files in the user’s repo; and the user approves the diff before shipping it. There is no dashboard-only publishing step, no second model subscription, and no per-credit metering claim to rely on.

For broader structure, topic clusters and related pages can help decide whether a concept needs a standalone page. The optional cloud tier adds search data and research features, while the local workflow can inspect and edit repository files without handing publishing control to a service.

Choose a page URL for a standalone topic and a fragment when the reader needs a precise section inside an existing page.

How to audit anchor links in a codebase

Fragment bugs usually appear after a heading is renamed, a Markdown slug changes, or a component stops rendering an expected section. Audit the source and the rendered page together.

1. Search templates, Markdown, components, and generated HTML for href="# and URL values containing #.
2. Extract each fragment and compare it with rendered id attributes.
3. Check for duplicate IDs. A fragment should resolve to one intended destination.
4. Test encoded values such as spaces, accented characters, and punctuation. Prefer hand-written stable IDs for public sections.
5. Open the rendered link with keyboard focus and check whether a sticky header covers the target.
6. After template changes, run the site’s build and link checks before merging.

# Find fragment links in a repository
grep -RIn 'href="#\|href="[^" ]*#' apps/ src/ content/

The command is a starting point, not a complete parser. A coding agent can inspect the relevant files, trace generated headings, compare links with IDs, and propose a small diff. Review that diff before shipping. Ask it to report missing targets and duplicate IDs separately so a valid warning does not get buried in a large content rewrite.

For example, if /docs/install contains id="environment" but a component still emits href="#env", the audit should identify the mismatch and show the file containing each value. The fix belongs in the repository source, followed by a browser test against the built page.

Anchor link best practices

Good anchor links remain understandable after a page grows and after another developer inherits the code. Keep the editorial decision visible in the markup.

• Use descriptive anchor text such as “See authentication requirements.”
• Match the link wording to the destination heading.
• Use lowercase, hyphenated, unique IDs.
• Keep public fragments stable; add a redirect or compatibility target before removing a widely used ID.
• Use links where they answer a navigation need, not after every repeated keyword.
• Test focus order, keyboard activation, screen-reader announcements, and the final scroll position.
• Prefer a real <a href> element over a click handler attached to a <div>.

When not to use an anchor link

Skip a fragment when the destination is too small to deserve a navigable stop, when the page structure changes on every render, or when a separate URL would better represent the subject. Also avoid adding fragments to links that must work across an unknown version of a page. A stable page URL is safer when the section ID is controlled by a third-party renderer.

Troubleshooting checklist

• Nothing happens: confirm that the target ID exists in the rendered HTML, not only in a source file.
• The wrong section opens: remove duplicate IDs and inspect component loops.
• The URL contains encoded characters: replace generated text IDs with explicit lowercase IDs.
• The heading sits beneath navigation: add an appropriate scroll-margin-top value.
• A link broke after editing: search the repository for the old fragment before renaming or deleting it.

For sites where content and metadata live in a repository, SEOAgent’s SEO optimization workflow can propose audit and markup changes for approval. If the page also needs new prose, the AI content writer capability can draft it, while the developer keeps the final change in version control.

Test anchor links against rendered HTML, because source-level IDs can disappear or change during component and Markdown generation.

Commit fragment changes with the same care as URL changes. Search for inbound references, preserve stable IDs, and verify the final page with keyboard navigation before merging.

References

• Creating links, MDN
• HTML Standard, WHATWG
• URI fragment, MDN
• W3C H30: Providing link text that describes link purpose