How do I create an internal link to a section of the same page?
Quick answer
Add a concise, descriptive id to the section you want to reach, then put that exact value after # in the link’s href. For example, <h2 id="setup">Setup</h2> pairs with <a href="#setup">Go to Setup</a>. Keep the values matched, use distinct ids for intended destinations, and check the link in the rendered page. A fragment addresses content within a page. [S1][S2]
The question, the details, the next step.
What are the two parts of an internal link to a section?
You need a destination and a link to it. Add an id to the element you want people to reach, often its heading. In the link, put that id after # in the href. Google’s developer guidance describes this heading-and-fragment pattern and recommends concise, descriptive custom ids. [S1]
<h2 id="project-setup">Project setup</h2>
<a href="#project-setup">Go to Project setup</a>Here, project-setup is the destination label, and #project-setup refers to it on the same page. [S1][S2] The fragment and destination id must match.
How should I choose an id if I might edit the heading later?
Choose a short, descriptive label for the section rather than depending on the heading’s exact wording. For example, a heading called “Before you begin” could have the id preparation:
<h2 id="preparation">Before you begin</h2>
<a href="#preparation">Jump to preparation</a>The visible heading and link text do not have to be the id. What matters for the destination is that the link’s fragment matches the element’s id. Google recommends stable custom anchors as a way to help prevent links breaking when a heading is revised. [S1] If you keep the id, make sure the link still points to it.
What should I check if the link doesn’t go to the section I expect?
Compare the destination’s id with the value after # in the link’s href. Look for a typo, a missing #, or a link pointing to a different label. For example, this destination:
<h2 id="billing-options">Billing options</h2>needs a link like:
<a href="#billing-options">See billing options</a>#billing-option does not match billing-options. Also check that each intended destination has its own id, so you can tell which section a link is meant to reach. Then view the rendered page and click the link to check where it goes. The cited guidance explains the id-and-fragment pattern but does not specify a universal method for validating duplicate ids.
Does a fragment open a different page or load another section of content?
A URL fragment is intended to address content within the same page; it is not a substitute for a distinct page URL or a way to load different page content. [S2] For an on-page jump, use a fragment such as #preparation and make sure the page has an element with id="preparation".
Before publishing, check the link in the rendered page and confirm it reaches the intended section. Website editors can present different editing and preview workflows, so if the destination does not behave as expected, check how your editor represents ids and links.
A practical checklist
Add a concise, descriptive
idto the destination element.Set the link’s
hrefto#followed by the exact same id.Give each intended destination its own id.
After editing a heading, confirm the id and link still match.
Click the link in the rendered page and check that it reaches the intended section.
A few more useful answers
Does the visible link text have to match the destination id?
No. The visible link text can be different. The fragment after # must match the destination element’s id.
Will changing a heading necessarily break its link?
Not if the destination keeps its custom id and the link still points to it. Stable custom anchors can help prevent links breaking when headings are revised. [S1]
Does a fragment create a separate page?
No. A fragment addresses content within a page; it is not a replacement for a distinct page URL. [S2]
Sources
References used for this guide.
- [S1] Make headings into link targets developers.google.com · Checked
- [S2] Frequently asked questions about JavaScript and links developers.google.com · Checked