View source for Template:Multicol/doc

{{Documentation subpage}}
<!--
    PLEASE ADD CATEGORIES AT THE BOTTOM OF THIS PAGE
    YOU CAN EDIT THE TEMPLATE DOCUMENTATION BELOW THIS COMMENT
-->
{{Aligned table
 |col1style=padding-right:3.0em;
 | {{tlx|Multicol|[''overall width'']|[''gutter width'']}}
                          | {{tlx|Start multicol|[''overall width'']|[''gutter width'']}}
 | ……                     | ……
 | {{tlx|Multicol break}} | {{tlx|Break multicol}}
 | ……                     | ……
 | {{tc|Multicol break}}  | {{tc|Break multicol}}
 | ……                     | ……
 | (etc)          | (etc)
 | {{tlx|Multicol end}}   | {{tlx|End multicol}}
}}

== Usage ==

<code>{{tl|Multicol}}</code> or <code>{{tl|Start multicol}}</code> is used to start a multi-columned section of a page. Between each column's contents, insert <code>{{tl|Multicol break}}</code> or <code>{{tl|Break multicol}}</code> and close the last column with <code>{{tl|Multicol end}}</code> or <code>{{tl|End multicol}}</code>. For example:

<pre>
<div style="background:lavender;">
{{Multicol}}              [or {{Start multicol}}]
First column's contents.
{{Multicol break}}        [or {{Break multicol}}]
Second column's contents.
{{Multicol break}}
Third column's contents.
{{Multicol end}}          [or {{End multicol}}]
</div>
</pre>

…produces:
<div style="background:lavender;">
{{Multicol}}
First column's contents.
{{Multicol break}}
Second column's contents.
{{Multicol break}}
Third column's contents.
{{Multicol end}}
</div>

Each column will be the same width (equally dividing the available horizontal space) and will include a small 20-pixel righthand margin (a "gutter") that prevents the contents in one column from touching those in the column to its right. (For further examples of how this template can be used, see [[User:Franl|User:franl's userpage]].)

While it is technically possible to have many columns, [[Wikipedia:Accessibility|accessibility]] implies that the use of any more than four or five should usually be avoided. If the number of items listed is fewer than six (e.g. fewer than two columns of three items), a column-based format is probably also best avoided.

== Parameters ==

This template has two optional parameters: the overall width of the set of columns and the width of the gutter.  The overall width of the set of columns can be an absolute value (e.g. <code>40em</code>) or a percentage of the available page width (e.g. <code>50%</code>). It defaults to <code>100%</code>. The second parameter is the gutter used between columns (which, as mentioned above, defaults to 20px).

{{tlf|Multicol break}}{{\}}{{tlf|Break multicol}} also takes an optional parameter for the gutter to its right, defaulting to 20px.

== Example ==

To create a three-column section, with four-pixel righthand gutters, that extends across 50% of the available width:
<pre>
{{Start multicol |50% |4px}}
First column's contents.
{{Break multicol |4px}}
Second column's contents.
{{Break multicol |4px}}
Third column's contents.
{{End multicol}}
</pre>
Result:
{{Start multicol |50% |4px}}
First column's contents.
{{Break multicol |4px}}
Second column's contents.
{{Break multicol |4px}}
Third column's contents.
{{End multicol}}

A {{tlf|Multicol}}umned region is left-aligned with regard to the area of the page (the "block") it occupies. This may be switched to a centered or righthand alignment thus:
{{Start multicol}}
; {{bigger|Centered}}
<pre>
 <div style="text-align:center;">
 {{startcenter}}
 {{Start multicol (...) }}
 ......
 {{End multicol}}
 {{endcenter}}
 </div>
</pre>
{{Break multicol}}
; {{bigger|Righthand side}}
<pre>
 <div style="text-align:right;">
 {{Start multicol (...) }}
 ......
 {{End multicol}}
 </div>
</pre>
{{End multicol}}

== Related templates ==

Layouts rendered by {{tl|Multicol}} and accompanying templates may also be produced by {{tl|Col-begin}} and its accompanying templates, but, depending on context and requirements, it may be easier to use one set rather than the other. Each of the following examples produce the same three-column table in which all columns have equal width:

<center>
{{Multicol|50%}}
<pre>
{{Multicol}}
Column 1
{{Multicol-break}}
Column 2
{{Multicol-break}}
Column 3
{{Multicol-end}}
</pre>
{{Multicol-break}}
<pre>
{{Col-begin}}
{{Col-3}}
Column 1
{{Col-3}}
Column 2
{{Col-3}}
Column 3
{{Col-end}}
</pre>
{{Multicol-end}}
</center>

It's simpler to add more columns to the {{tl|Multicol}} example than to the {{tl|Col-begin}} example, because in the latter case, all occurrences of {{tl|Col-3}} would need to be changed to {{tl|Col-4}}.

'''These templates groups are not interchangeable.'''  If you start with {{tl|Multicol}}, but end with the plain {{tl|col-end}} templates, then you'll have an unclosed <nowiki><div></nowiki> tag that can harm the formatting of the rest of the page.  The problems created by mixing these templates is not easily visible for all users, so please don't assume that it's working properly just because it looks right for you.  If you start with {{tl|Multicol}}, then you must use {{tl|Multicol-break}} and {{tl|Multicol-end}}, not {{tl|col-break}} and {{tl|col-end}} (and vice versa).

===TemplateData===
{{#switch: {{PAGENAME}}
|Multicol/doc
|Multicol =
{{TemplateDataHeader|multicol}}
<templatedata>
{
    "description": "Starts a multi-column section. Subsequent columns are started by {{multicol-break}} and the section is ended with {{multicol-end}}",
    "params": {
        "1": {
            "label": "Table width",
            "description": "Width of table, a CSS width e.g. '50%'.",
            "type": "string",
            "default": "100%",
            "required": false
        },
        "2": {
            "label": "Column width",
            "description": "Width of the first column.",
            "type": "string",
            "default": "20px",
            "required": false
        }
    }
}
</templatedata>
}}

{{#switch: {{PAGENAME}}
|Multicol/doc
|Multicol-break =
{{TemplateDataHeader|Multicol-break}}

<templatedata>
{
    "description": "Starts another column in a table started by {{multicol}}.",
    "params": {
        "1": {
            "label": "Column width",
            "description": "Width of the column.",
            "type": "string",
            "default": "20px",
            "required": false
        }
    }
}
</templatedata>
}}

{{#switch: {{PAGENAME}}
|Multicol/doc
|Multicol-end =
{{TemplateDataHeader|Multicol-end}}
<templatedata>
{
    "description": "Ends a multi-column list started by {{multicol}}. The template takes no parameters.",
    "params": {
    }
}
</templatedata>
}}

== See also ==
{{Column-generating template families}}

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox |
| <!-- Categories below this line, please; interwikis to Wikidata. -->
[[Category:Multi-column templates]]
}}</includeonly>