Making headings into link targets

To make headings into link targets, add an anchor. To avoid breaking existing links to headings in published content, create an anchor that uses the same ID string as the published page. You can find the ID string by inspecting the heading. You might also create a custom anchor for a long heading that you'd like a shorter anchor for. Anchors are especially good for sections of documents that are linked to a lot; having a custom anchor reduces the likelihood of breaking existing links if the heading text changes.

Adding an anchor

In some content management systems, anchors are automatically created for headings.

HTML

To add an anchor to a heading in HTML, do the following:

  • Add a <section> element with an id attribute. Don't use <a name>.
  • Use lowercase for id values, and put hyphens between words.

For example:

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>
  

Acceptable:

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

Recommended:

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

Markdown

To add an anchor to a heading in Markdown, do the following:

  • Add the following to the end of the line that the heading is on:

    {:#ID_OF_ANCHOR}

    Replace ID_OF_ANCHOR with the ID for this heading.
  • Use lowercase for id values, and put hyphens between words.

For example:

Not recommended:

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

Not recommended:

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

Acceptable:

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

Recommended:

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

Also recommended:

  ## Help conserve habitat for pollinators {:#conserve-habitat}
  ### Obtaining test permissions {:#test-perms}
  ### Listing all tests for a project {:#listing-tests}
  ## Viewing test results {:#viewing-tests}
  ### Configure two VM instances {:#configure-vms}
  ## Setting an access control policy {:#set-policy}

Changing an anchor

In some content management systems, anchors are automatically created for headings. If you're changing the heading, you need to create a custom anchor that uses the older ID string so that you avoid breaking existing links. You can find the ID string by inspecting the heading.

HTML

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.

For example:

Recommended:

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

Markdown

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.

For example:

Recommended:

    ## Introduction to everything {:#introduction_to_some_things}