Making headings into link targets

In some content management systems, anchors are automatically created for headings. However, you might want to add a custom anchor to a heading for several reasons:

  • You want to use an anchor that's shorter than the automatically generated anchor.
  • You want to use an anchor for content that might be frequently linked to. Adding a custom anchor reduces the likelihood of breaking existing links if the heading text changes later.
  • You want to revise a heading. If the anchor for the heading is generated automatically, then the anchor changes when you revise the heading, breaking existing links.

Add a custom anchor

HTML

To add an anchor to a heading in HTML, add a <section> element with an id attribute. Don't use <a name>. Use lowercase for id values, and put hyphens between words.

Recommended:

  <section id="introduction-to-everything">
  <h2>Introduction to everything</h2>
  ...
  </section>
  

Acceptable:

  <h2 id="introduction-to-everything">Introduction to everything</h2>
  

Not recommended:

  <h2><a name="Introduction_To_Everything">Introduction to everything</a></h2>
  

Not recommended:

  <a name="Introduction_To_Everything"></a>
  <h2>Introduction to everything</h2>
  

Markdown

To add an anchor to a heading in Markdown, add the following code to the end of the line that the heading is on. Replace ID_OF_ANCHOR with the ID for this heading. Use lowercase for id values, and put hyphens between words.

{: #ID_OF_ANCHOR }

Recommended:

## Help conserve habitat for pollinators {: #help-conserve-habitat-for-pollinators }

Also recommended:

## Help conserve habitat for pollinators {: #conserve-habitat }

Acceptable:

## Help conserve habitat for pollinators {: id='conserve-habitat' }

Acceptable:

## Help conserve habitat for pollinators {: id="conserve-habitat" }

Revise a heading

If you revise a heading in a content management system where anchors are automatically created, you can create a custom anchor to avoid breaking existing links. To create the custom anchor, use the older ID string. You can find the ID string by inspecting the heading on the published page.

For example, if you change a heading from Introduction to some things to Introduction to everything, then add a custom anchor that uses the older ID string and formatting.

HTML

<section id="introduction_to_some_things">
<h2>Introduction to everything</h2>
...
</section>

Markdown

## Introduction to everything {: #introduction_to_some_things }