Template:Anchor/doc

Usage
  or its plural alias    will insert one or more HTML anchors in a page at the location of its invocation, enabling direct #Links to this location.

Linking
After that, you can have links sending directly to the line you marked:


 * With  or also assuming use of "link label in  , then  when linking from the same page
 * With  or   when linking from another page.

Usage details

 * Code :


 * Gives : BeforeAfter

Heading title

 * This results in "#Foo" and "#Bar & Baz" being alias targets of "#Heading title" which may be subject to change. Anchors are a way to keep links "healthy" despite such local changes. This syntax doesn't alter the heading, which remains a regular heading as functional as if the template wasn't inserted (i.e. still appears in the page's TOC, and section editing works as usual). This method is advantageous in that you can always see the anchors list when editing this section only, and they work exactly like the heading's own regular anchor. (This is not the case when the anchors are added one line above or below the heading.
 * It is better however to add anchors after the heading on the next line, for the anchors in a section title echo inside any section edit summary and work just as well.

Heading title
Next text line...
 * Inside a heading, inserting the anchor code before or after the actual heading title works mostly the same. Putting it before the heading makes it work more like an actual heading anchor in more web browsers, but putting it after the heading makes the regular heading more readable and easy to find. Having a space between the template and the heading title is inconsequential, but adding a space keeps it more readable, but does impact the length of section edit titles.
 * Even when you have many long aliases, you need to keep the heading and its embedded anchors on a single line (which may be very long and wrap), as its own single paragraph. Trying to use a vertical format for the template would give all the appearances of working, including section numbering, but actually trying to edit the section results in editing the next section instead, due to a bug. So, in headings, do not use here a vertical format such as:

 ==George Walker Bush == |}}


 * Though aliases and  will work interchangeably, it is preferable to use the singular alias for a single anchor, and the plural alias for multiple anchors. This will allow Special:WhatLinksHere/Template:s to track usage of multiple anchors, and could help detecting and converting old-style   to  . So for maintenance needs, we'd appreciate you maintain the suggested convention.

Known bug

 * Currently, the anchor code is included in a section-edit summary. For instance, section-editing the "Notes" section of this page will pre-fill your edit summary with:
 * This is inconsequential for your edit, but can be inconvenient for your edit summary when there are many long anchor names. You can however edit it out to just:
 * This bug can't be helped in the template itself. It is hoped, not promised, that a future version of the MediaWiki software will skip template calls in headings for section-edit summaries{{#ifeq:{{BASEPAGENAME}}|Anchor|.
 * This bug can't be helped in the template itself. It is hoped, not promised, that a future version of the MediaWiki software will skip template calls in headings for section-edit summaries{{#ifeq:{{BASEPAGENAME}}|Anchor|.
 * This bug can't be helped in the template itself. It is hoped, not promised, that a future version of the MediaWiki software will skip template calls in headings for section-edit summaries{{#ifeq:{{BASEPAGENAME}}|Anchor|.

Tips

 * When you make a link from article A to article B#Heading, you can preemptively edit article B from
 * To:
 * (Note the singular "Anchor" here.) This will ensure the perennity of any link to #Heading, regardless of how the actual heading may be changed in the future. Since you can't expect other editors to mind your target anchors, this solution is more efficient and proactive than just adding an HTML comment "this heading is linked from article A" next to the heading. ''Such a comment is still a good idea though&mdash;most editors will have no clue as to what an is or does. The comment makes the link existence, dependency, and need plain.
 * (Note the singular "Anchor" here.) This will ensure the perennity of any link to #Heading, regardless of how the actual heading may be changed in the future. Since you can't expect other editors to mind your target anchors, this solution is more efficient and proactive than just adding an HTML comment "this heading is linked from article A" next to the heading. ''Such a comment is still a good idea though&mdash;most editors will have no clue as to what an is or does. The comment makes the link existence, dependency, and need plain.
 * (Note the singular "Anchor" here.) This will ensure the perennity of any link to #Heading, regardless of how the actual heading may be changed in the future. Since you can't expect other editors to mind your target anchors, this solution is more efficient and proactive than just adding an HTML comment "this heading is linked from article A" next to the heading. ''Such a comment is still a good idea though&mdash;most editors will have no clue as to what an is or does. The comment makes the link existence, dependency, and need plain.


 * Similarly, when you add an anchor alias to a heading, you can preemptively add a copy-paste of the current heading's title along with your new anchor. For instance, for adding a "#Regions" anchor to this heading:
 * You would make it:
 * (Note the plural "Anchors" here.) This too will ensure the longevity of both "#Current division" and "#Regions", regardless of other editors' future edits on the heading.|.}}
 * (Note the plural "Anchors" here.) This too will ensure the longevity of both "#Current division" and "#Regions", regardless of other editors' future edits on the heading.|.}}
 * (Note the plural "Anchors" here.) This too will ensure the longevity of both "#Current division" and "#Regions", regardless of other editors' future edits on the heading.|.}}

Anchor names

 * Due to technical limitations, anchor names can not include characters "#" (hash), "&#124;" (pipe) or "&#61;" (equal). On the other hand, special characters such as " " (space), "," (comma), "&" (ampersand), etc. can be used directly both in anchors and links, because the software will process them automatically into a URL-compatible format.
 * Anchor names should preferably be written in "Sentence case" (as is the standard for headings and thus their anchors); that is, capitalize the first letter of the first word and any proper nouns, but leave the rest lowercase. Examples: "The title of my anchor", "The anchor from Ipanema", etc. Because some browsers have case-sensitive anchors, the anchor name used in a #Link should be absolutely identical to its target (rather than all-lowercase).
 * Anchor names should be unique (with respect to all heading titles and additional anchors) on each page; a duplicate anchor won't work since the #Links will always go to the first homonymous anchor on the page.

Technical

 * The template is based on
 * The final HTML page (as outputted by Wikipedia to the reader's browser) will have converted it to  instead.
 * The more backward-compatible  is used by Wikipedia's own headings but disabled for editors in the wikicode and thus not used here.