View source for Template:Markupv/doc

{{Documentation subpage}}<!-- Please add category links where indicated at the bottom of this page and interwiki links at Wikidata. Thank you. -->
{{Uses TemplateStyles|Template:Markup/styles.css}}
This template is used to present wiki markup or code in a vertical format with the rendered output beneath it.

== Usage ==

=== Parameters ===
{| class="wikitable"
 ! scope="row" style="line-height: 2;" | {{Para|markup}}<br />{{Para|m}}
 | The code/markup ("wikitext"), wrapped in {{Tag|nowiki}} tags so it will be displayed ''as-is''
 |-
 ! scope="row" style="line-height: 2;" | {{Para|renders}}<br />{{Para|r}}
 | The same code markup, but ''without'' the {{Tag|nowiki}} tags, so that it ''will'' be parsed
 |-
 ! scope="row" style="line-height: 2;" | {{Para|title}}<br />{{Para|t}}
 | A title to display above the example pair ''(optional)''
 |-
 ! scope="row" style="line-height: 2;" | {{Para|tag}}
 | The name of a HTML tag (such as {{xtag|syntaxhighlight}}, {{xtag|pre}}, or {{xtag|div}}) to wrap the markup with ''(optional)''
 |-
 ! scope="row" style="line-height: 2;" | {{Para|margin}}
 | Size of the indentation from the left margin, in [[Em (typography)|em units]]; numeric values only, do not include {{Code|em}} unit suffix ''(optional)''
 |-
 ! scope="row" style="line-height: 2;" | {{Para|style}}
 | Additional CSS declarations for the whole table ''(optional)''<br/>CSS style declarations for the title ({{para|tstyle}}), markup ({{para|mstyle}}), and render ({{para|rstyle}}) can also be specified separately (all ''optional'')
|}

The ''Markup'' cell is pre-formatted with {{Tag|pre|o}} to retain newlines and spaces, but styled to allow content to wrap within the cell. It is usually desirable to escape the content of the ''Markup'' cell so that the markup is displayed by wrapping the markup in {{Xtag|nowiki}}. It is not technically possible to build this feature into the template.

In the ''Renders as'' cell, the content is usually the unescaped markup copied from the ''Markup'' cell. There are instances where this may differ:
* If the first line includes wikimarkup that must start on a new line such as {{code|#}}, {{code|*}}  or {{code|;}} then use {{Tag|nowiki|s}} before the first line.
** Use {{para|tag|pre}} or {{para|tag|syntaxhighlight}} to prevent an empty line before the list in the ''Markup'' cell.
* Header markup such as {{Code|1===}} will show in the page table of contents; use {{Tlx|Fake heading}}.
* When using {{Tlx|Reflist}} with no other parameters, use {{Tlx|Reflist|2=close=1}} to ensure that the reference list is closed.
* Some templates will place the page in a maintenance category, which is usually undesired:
** Instead of {{Tlx|Citation needed}}, use {{Tlx|Fake citation needed}}.
* Some templates may have error checking that places the page in a maintenance category. Suppress the category as possible:
** {{Cs1}} templates can suppress the maintenance category by setting {{Para|template doc demo|true}}.

=== Limitations ===
If you don't wrap the content of the markup cell in {{Xtag|nowiki}}, then any template markup will not be escaped, it will be expanded.

This example shows the markup for {{Template link general|plaincode=on|tl|Tag}}:
{{Markupv|tag=syntaxhighlight|m=<nowiki>{{tl|Tag}}</nowiki>|r={{tl|Tag}}}}

Without {{Xtag|nowiki}} the previous example would instead display:
{{Markupv|tag=syntaxhighlight|m={{tl|Tag}}|r={{tl|Tag}}}}

== Examples ==
=== Simple ===
{{Markupv|tag=syntaxhighlight|m=<nowiki>'''Bold text'''</nowiki>|r='''Bold text'''}}

{{Markupv|tag=syntaxhighlight|m=<nowiki>''Italic text''</nowiki>|r=''Italic text''}}

=== Meta ===
The following meta-example uses {{Tlf|Markupv}} to create an example of using {{Tag|score}}:
<syntaxhighlight lang="wikitext">
{{Markupv|tag=syntaxhighlight|title=Example:
 | markup  = <nowiki><score>\relative c' { c( b~ c b c b c b c~ c)}</score></nowiki>
 | renders = <score>\relative c' { c( b~ c b c b c b c~ c)}</score>
}}
</syntaxhighlight>

…it generates:
{{Markupv|tag=syntaxhighlight|title=Example:|markup=<nowiki><score>\relative c' { c( b~ c b c b c b c~ c)}</score></nowiki>|renders=<score>\relative c' { c( b~ c b c b c b c~ c)}</score>}}

=== Complex ===
{{Block indent|▶ ''Note that the second argument to'' {{Template link general|Markupv}} ''uses'' {{Template link general|Fake heading}}.}}
{{Markupv|tag=syntaxhighlight
 | m = <nowiki>The quick brown fox jumps over the lazy dog.{{#tag:ref|A footnote.<ref>A reference for the footnote.</ref>|group=nb}} The cow jumped over the moon.{{Citation needed}}

== Notes ==
{{Reflist|group=nb}}

== References ==
{{Reflist}}</nowiki>
 | r = The quick brown fox jumps over the lazy dog.{{#tag:ref|A footnote.<ref>A reference for the footnote.</ref>|group=nb}} The cow jumped over the moon.{{Citation needed}}

{{Fake heading|sub=3|Notes}}
{{Reflist|group=nb}}

{{Fake heading|sub=3|References}}
{{Reflist|close}}}}

=== With title ===
{{Markupv|title=Foxes and dogs|m=The quick brown fox jumps over the lazy dog.|r=The quick brown fox jumps over the lazy dog.}}

=== Wrapped in "code" tags ===
When a template is enclosed within {{Template link general|Code}}, it shows the rendered HTML:

<div class="overflowbugx" style="overflow-x:auto;">
{{Markupv|title=With "code" tags|tstyle=text-align: left|m=<nowiki>{{Code|{{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}}}</nowiki>|r={{Code|{{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}}}}}
</div>

This can also be achieved by setting {{para|tag|code}}:

<div class="overflowbugx" style="overflow-x:auto;">
{{Markupv|title=With "tag" parameter|tstyle=text-align: left|tag=code|m=<nowiki>{{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}</nowiki>|r={{Code|{{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}}}}}
</div>

For comparison:

{{Markupv|title=With "syntaxhighlight", not "code"|tstyle=text-align: left|tag=syntaxhighlight|m=<nowiki>{{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}</nowiki>|r={{Cite book|last=White|first=T. H.|title=The Book of Merlyn|year=1977}}}}

== See also ==
* {{Template link general|Automarkup}}
* {{Template link general|Markup}} – provides a side-by-side presentation of markup and renderer output
* {{Template link general|Markup2}} – organizes examples vertically using bulleted lists/sublists

<includeonly>{{Sandbox other||<!-- Please place category links below this line and interwiki links at Wikidata. Thank you. -->
[[Category:Documentation assistance templates]]
[[Category:Template namespace templates]]
[[Category:Template test cases| ]]
}}</includeonly>