Stay organized with collectionsSave and categorize content based on your preferences.
This page discusses how to turn a heading into a link target by using anidattribute. For more information about how to format headings, seeHeadings and titles.
In some content management systems, anchors are automatically created for headings. However, you
might want to add acustomanchor 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 torevise a heading. If the
anchor for the heading is generated automatically, then the anchor changes when you revise
the heading, breaking existing links.
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. If the heading already has a
custom anchor, don't change the anchor unless it contains a term that you want to remove (such as
a disrespectful term).
To create the custom anchor, use the older ID string for the heading. You can find the ID
string by inspecting the heading on the published page. For example, if you change a heading fromIntroduction to some thingstoIntroduction to everything, then add a custom anchor
that uses the older ID string and formatting.
If you need to change an existing custom anchor, you should check your content management
system to update any links that use the old anchor. Inbound links that use the old anchor still
reach the page but not the specific section or heading.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eTurn a heading into a link target by adding an \u003ccode\u003eid\u003c/code\u003e attribute within a \u003ccode\u003e<section>\u003c/code\u003e element or directly to the heading tag in HTML.\u003c/p\u003e\n"],["\u003cp\u003eWhen creating custom anchors, use lowercase letters, hyphens between words, and ensure they are descriptive yet concise.\u003c/p\u003e\n"],["\u003cp\u003eConsider adding custom anchors for frequently linked content or when revising headings to prevent broken links.\u003c/p\u003e\n"],["\u003cp\u003eIf revising a heading with an existing anchor, create a new custom anchor using the older ID to maintain link functionality, or update existing links if changing the anchor.\u003c/p\u003e\n"]]],["To create custom anchors for headings, use the `id` attribute within a `\u003csection\u003e` tag in HTML or `{: #ID_OF_ANCHOR }` in Markdown. This allows for shorter, stable anchors, reducing the risk of broken links. Use lowercase letters and hyphens in the anchor text. When revising headings, retain the original ID string as a custom anchor to preserve existing links. Update any links to reflect changed custom anchors. Avoid using `\u003ca name\u003e` attributes.\n"],null,["This page discusses how to turn a heading into a link target by using an\n`id` attribute. For more information about how to format headings, see\n[Headings and titles](/style/headings).\n\nIn some content management systems, anchors are automatically created for headings. However, you\nmight want to add a *custom* anchor to a heading for several reasons:\n\n- You want to use an anchor that's shorter than the automatically generated anchor.\n- 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.\n- You want to [revise a heading](#changing-an-anchor). If the anchor for the heading is generated automatically, then the anchor changes when you revise the heading, breaking existing links.\n\n\nAdd a custom anchor\n\nHTML\n\nTo add an anchor to a heading in HTML, add a `section` element\nwith an `id` attribute. Don't use an `a` element with\na `name` attribute. For anchor text, use lowercase letters, and\nput hyphens between words. In the following, replace\n\u003cvar translate=\"no\"\u003eID_OF_ANCHOR\u003c/var\u003e with your anchor text---for example,\n`introduction-to-everything`. \n\n```\n \u003csection id=\"ID_OF_ANCHOR\"\u003e\u003c/section\u003e\n \n``` \nRecommended: \n\n```\n \u003csection id=\"introduction-to-everything\"\u003e\n \u003ch2\u003eIntroduction to everything\u003c/h2\u003e\n ...\n \u003c/section\u003e\n \n```\n\nAcceptable: \n\n```\n \u003ch2 id=\"introduction-to-everything\"\u003eIntroduction to everything\u003c/h2\u003e\n \n```\n\nNot recommended: \n\n```\n \u003ch2\u003e\u003ca name=\"Introduction_To_Everything\"\u003eIntroduction to everything\u003c/a\u003e\u003c/h2\u003e\n \n```\n\nNot recommended: \n\n```\n \u003ca name=\"Introduction_To_Everything\"\u003e\u003c/a\u003e\n \u003ch2\u003eIntroduction to everything\u003c/h2\u003e\n \n```\n\nMarkdown\n\nTo add an anchor to a heading in Markdown, add the following code to the\nend of the line that the heading is on. For anchor text, use lowercase\nletters, and put hyphens between words. In the following, replace\n\u003cvar translate=\"no\"\u003eID_OF_ANCHOR\u003c/var\u003e with your anchor text---for example,\n`conserve-habitat`. \n\n```\n{: #ID_OF_ANCHOR }\n``` \nRecommended: \n\n```\n## Help conserve habitat for pollinators {: #help-conserve-habitat-for-pollinators }\n```\n\nAlso recommended: \n\n```\n## Help conserve habitat for pollinators {: #conserve-habitat }\n```\n\nAcceptable: \n\n```\n## Help conserve habitat for pollinators {: id='conserve-habitat' }\n```\n\nAcceptable: \n\n```\n## Help conserve habitat for pollinators {: id=\"conserve-habitat\" }\n```\n\nRevise a heading\n\nIf you revise a heading in a content management system where anchors are automatically created,\nyou can create a custom anchor to avoid breaking existing links. If the heading already has a\ncustom anchor, don't change the anchor unless it contains a term that you want to remove (such as\na disrespectful term).\n\nTo create the custom anchor, use the older ID string for the heading. You can find the ID\nstring by inspecting the heading on the published page. For example, if you change a heading from\n*Introduction to some things* to *Introduction to everything*, then add a custom anchor\nthat uses the older ID string and formatting.\n\nHTML \n\n```\n\u003csection id=\"introduction-to-some-things\"\u003e\n\u003ch2\u003eIntroduction to everything\u003c/h2\u003e\n...\n\u003c/section\u003e\n```\n\nMarkdown \n\n```\n## Introduction to everything {: #introduction-to-some-things }\n```\n\nIf you need to change an existing custom anchor, you should check your content management\nsystem to update any links that use the old anchor. Inbound links that use the old anchor still\nreach the page but not the specific section or heading."]]
