How to add anchor links to headings in WordPress

Step by step

1. Add the anchor to the heading

1. Click the heading in the block editor.
2. In the sidebar, open the Block tab and expand Advanced.
3. Type the anchor into HTML anchor.
4. Update the post.

The heading is now printed as <h2 id="brewing-ratio">. The field is available on many blocks, not only headings, so you can also target an image or a group.

2. Follow the naming rules

• Lowercase letters, digits and hyphens only. No spaces.
• Start with a letter, which keeps the id usable in CSS selectors.
• Unique on the page. Two elements with the same id break the link to the second one.
• Short and descriptive of the section, since the anchor is visible in the URL people share.
• Not comments or respond. WordPress themes use those ids for the comment list and comment form.

3. Link to it from the same page

Select the text that should jump, press the link shortcut (Ctrl+K or ⌘K), type #brewing-ratio and press Enter. The link is saved as <a href="#brewing-ratio">. Clicking it scrolls to the heading without reloading the page.

4. Link to it from another page

Use the full address with the fragment on the end: https://example.com/pour-over-guide/#brewing-ratio. Put the fragment after the trailing slash and after any query string. This is the form to use in other posts, menus and newsletters.

5. In the Classic editor or raw HTML

Switch to the Text tab and add an id to the heading yourself:

<h2 id="brewing-ratio">Brewing ratio</h2>
<p>Skip to <a href="#brewing-ratio">the brewing ratio</a>.</p>

An older pattern uses an empty <a name="…"> element as the target. The id attribute on the heading does the same job with less markup.

6. Fix headings that hide under a sticky header

If your theme has a fixed header, a jump lands with the heading tucked behind it. One CSS rule fixes every anchor on the site. Add it under Appearance → Customize → Additional CSS, or in the Site Editor's additional CSS:

:target,
h2[id],
h3[id] {
  scroll-margin-top: 90px;
}

Set the value a little larger than the header's height. scroll-margin-top tells the browser to stop scrolling that far above the element.

7. Test the links

Open the page in a private window and click each jump link. Then paste the full URL with its fragment into a new tab and confirm it lands on the right section. Check on a phone as well, where sticky headers are often a different height.

Building a table of contents from anchors

Once headings have anchors, a table of contents is a list of links to them. You can write that list by hand, or let it build itself. Hydrogen SEO's Table of Contents block, or the [hydrogen_seo_toc] shortcode, lists the headings in a post and links to each. A heading that already has an HTML anchor keeps it, and a listed heading without one gets an id made from its text, so "Brewing ratio: 1 to 16" becomes brewing-ratio-1-to-16. Duplicates get a number, such as summary-2. Options and markup are in the table of contents documentation.

Do anchors help in search

A fragment is not a separate page. Search engines index the page, not #brewing-ratio. What anchors can do is let Google link a result directly to a section: it sometimes shows "jump to" style links or sends a featured-snippet click to the relevant passage, and well-labelled headings with ids make that possible. There is no markup that guarantees it. The dependable benefit is for readers and for your own internal links, which can point at the exact answer.

Keep anchors stable

An anchor is part of a URL once someone has linked to it. If you rename it, old links still open the page but land at the top. So choose the name once and leave it alone when you reword the heading. This is the main reason to set an HTML anchor by hand on important sections instead of relying on ids generated from the heading text, which change when the text does.