Editing Template:Visible anchor/doc

{{Documentation subpage}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
{{High-use}}
{{tsh|va|visanc|vanchor}}
{{Uses TemplateStyles|Template:Visible anchor/styles.css}}
The template {{tnull|Visible anchor}} inserts one or more [[HTML element#Anchor|HTML anchors]] in a page. Those locations can then be linked to using <code><nowiki>[[#link|...]]</nowiki></code> syntax. Unlike {{tl|Anchor}}, the '''first parameter''' will be visible text on the page.

== Usage ==
<code><nowiki>{{visible anchor|anchor 1|anchor 2|text=display text|lang=language code}}</nowiki></code>

The template can be used with up to 10 anchor names. Anchor names are case sensitive, so <code><nowiki>{{Visible anchor|Anchor name 1}}</nowiki></code> and <code><nowiki>{{Visible anchor|Anchor Name 1}}</nowiki></code> are not equivalent. When making an anchor, in general capitalize the first letter of the anchor name, and follow the same capitalization guidelines as headers (see [[MOS:HEAD|Manual of Style: Headers]] for more information). An optional {{para|text}} parameter can be added in order to specify the text to display in the anchor. By default, the value of the first parameter is used. A second optional {{para|lang}} parameter can be added to mark up the resulting visible text with the specified ISO 639 language code or IETF language tag (such as used by {{tl|lang}}).

===Linking to anchors===

Link to an anchor in the same article using just the anchor name, e.g. <code><nowiki>[[#Anchor name]]</nowiki></code>. (In the Visual Editor, type <code>#Anchor name</code> into the link field.)

From a different article, link to an anchor by specifying the article name, followed by a <code><nowiki>#</nowiki></code>, then the anchor name. e.g. <code><nowiki>[[Article name#Anchor name]]</nowiki></code>.

The <code><nowiki>#</nowiki></code> will be visible in the link text. To prevent this, give the link a display title in the typical manner: After a pipe character (<code>|</code>) in the wikitext (<code><nowiki>[[#Anchor name|Anchor name]]</nowiki></code>), or by editing the text of the link in the Visual Editor.

===Destination highlighting===
When a link to an anchor is followed, the destination anchor's visible text will typically be highlighted with a shaded background. (May vary based on the reader's browser or selected wiki skin.) For example:<blockquote>''{{vanchor|this|text=This text anchor}}'' will be highlighted after following  [[#this|this link which targets it]].</blockquote>

===Specifying a language===
To aid screen readers and other assistive technologies properly identify text in foreign languages or dialects, an [[ISO 639-1]] language code or [[IETF language tag]] can be given with the {{para|lang}} parameter to add the language code as an attribute to the HTML of the displayed text. Note that unlike the {{tl|lang}} template, no italicization or text formatting is applied to the text.

== Examples ==
{| class="wikitable"1
! Code
! Result
! Link
|-
| <code><nowiki>{{vanchor|Foo}}</nowiki></code>
| {{vanchor|Foo}}
| [[#Foo]]
|-
| <code><nowiki>{{vanchor|Bar|Baz}}</nowiki></code>
| {{vanchor|Bar|Baz}}
| [[#Bar]], [[#Baz]]
|-
| <code><nowiki>{{vanchor|Qux|text=Display text}}</nowiki></code>
| {{vanchor|Qux|text=Display text}}
| [[#Qux]]
|-
| <code><nowiki>{{vanchor|Corge|Grault|lang=en-US}}</nowiki></code>
| {{vanchor|Corge|Grault|lang=en-US}}
| [[#Corge]], [[#Grault]]
|}

== Limitations ==
{|class="wikitable floatright"
|---
! Character
! [[Character entity reference|Code]]
! Template
! Meaning
|---
| "
| <code>&amp;quot;</code> <br /><code>&amp;#34;</code>
| {{N/a}}
| [[quotation mark]]
|---
| &#35;
| <code>&amp;#35;</code>
| {{N/a}}
| [[Number sign|hash]]
|---
| &#124;
| <code>&amp;#124;</code>
| {{tl|!}}
| [[Vertical bar|pipe]]
|---
| &#61;
| <code>&amp;#61;</code>
| {{tl|{{=}}}}
| [[Equals sign|equals]]
|}

* {{strong|This template should not be used within section headings.}} Doing so will result in broken links in edit summaries, as well as possible duplicate anchors (see the next bullet point).
* Anchor names should be unique on a page, and should not duplicate any heading titles. Duplicate anchors won't work as expected since the #links go to the first anchor with that name. Duplicate anchors also result in invalid HTML; you can check for duplicate anchors by running the page through the [[W3C Markup Validation Service]].
* Anchor names that contain any character shown in the table on the right will not work as expected. However, any of these characters can be replaced with the "&amp;#" codes shown for them here. Or, the pipe symbol and equals sign can be worked around with {{tl|!}} and {{tl|{{=}}}}, respectively. Markup code such as {{tag|sup|o}} and {{tag|sub|o}} (superscript and subscript) cannot be used. Most other characters, including white space and punctuation, are not a problem.
* The template can create a maximum of 10 anchors. Specifying more than 10 anchors will result in an error message.
* If positional parameters (parameters without specifying 1=, 2=, etc.) are used, whitespace and newlines will be preserved. If you instead specify the name of the parameters (e.g. {{para|1}}), whitespace and newlines will be trimmed.

== TemplateData ==
{{TemplateDataHeader}}
<templatedata>
{
	"params": {
		"1": {
			"label": "Anchor name, and text to display",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting; you can put formatting in the \"text\" parameter instead.",
			"example": "start-of-content",
			"type": "string",
			"required": true
		},
		"2": {
			"label": "Second anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string",
			"suggested": true
		},
		"3": {
			"label": "Third anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"4": {
			"label": "Fourth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"5": {
			"label": "Fifth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"6": {
			"label": "Sixth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"7": {
			"label": "Seventh anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"8": {
			"label": "Eighth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"9": {
			"label": "Ninth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"10": {
			"label": "Tenth anchor name",
			"description": "This will become an anchor. The characters \", #, | and = must be escaped; see the main template page for details. Do not try to use formatting.",
			"type": "string"
		},
		"text": {
			"label": "Display text",
			"description": "Overrides the display of parameter 1, but is not an anchor name. May be formatted.",
			"example": "Properties of CO<sub>2</sub>",
			"type": "content",
			"suggested": true
		},
		"lang": {
			"label": "Language code",
			"description": "Applies the specified ISO 639 or IETF language tag as an attribute to the HTML of the displayed text. Useful for screen readers and other assistive technologies.",
			"example": "en-US; fr; etc.",
			"type": "line"
		}
	},
	"description": "The template {{Visible anchor}} inserts one or more HTML anchors in a page. Those locations can then be linked to using [[#link|...]] syntax. Unlike {{Anchor}}, the first parameter will be visible text on the page."
}
</templatedata>

== See also ==
* {{tl|Anchor}}
* {{tl|Anchored list}}
* {{tl|Shortcut}}
* [[Help:Link#Section linking (anchors)|Help:Link §&nbsp;Section linking (anchors)]] (Shortcut: [[WP:ANCHOR]])

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Wikipedia formatting templates]]
}}</includeonly>