View source for Template:Multicol/doc

{{Documentation subpage}}
<!--
    PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE
    YOU CAN EDIT THE TEMPLATE DOCUMENTATION BELOW THIS COMMENT
-->
== Usage ==
{{tl|Multicol}} is used to start a multi-column section of a page. Between each block of column text insert <tt>{{tl|Multicol-break}}</tt> and close the last column with <tt>{{tl|Multicol-end}}</tt>. For example:

<pre>
{{Multicol}}
This text appears in the first column.
{{Multicol-break}}
This text appears in the second column.
{{Multicol-break}}
This text appears in the third column.
{{Multicol-end}}
</pre>

Provides this format:
{{Multicol}}
This text appears in the first column.
{{Multicol-break}}
This text appears in the second column.
{{Multicol-break}}
This text appears in the third column.
{{Multicol-end}}

Most pages use only two columns, but you can have any number of columns. Each column will be the same width, equally dividing the available horizontal space. Each column has a small right margin (20 pixels), creating a "gutter" that prevents text in one column from touching text in the column to its right. See [[User:Franl|franl]]'s user page for examples of how this template can be used.

While it is technically possible to have many columns, please consider the width of the items and avoid having more than about three or four columns for most pages because it is important to maintain legibility for the millions of readers who have smaller computer screens or are using smartphones to read articles.  Similarly, if the list is short (perhaps about five items), please avoid using columns at all.

== 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., <tt>40em</tt>) or a percentage of the available page width (e.g., <tt>50%</tt>). This parameter defaults to <tt>100%</tt>. The second parameter is the "gutter" for the whole column set, which defaults to 20px.

The {{tl|Multicol-break}} also takes an optional parameter for the gutter to its right, also defaulting to 20px.

For example, to create a 3-column section that is only 50% the width of the page, with 2-pixel right margins:

<pre>
{{Multicol|50%|2px}}
This text appears in the first column.
{{Multicol-break|2px}}
This text appears in the second column.
{{Multicol-break|2px}}
This text appears in the third column.
{{Multicol-end}}
</pre>

Provides this format:
{{Multicol|50%|2px}}
This text appears in the first column.
{{Multicol-break|2px}}
This text appears in the second column.
{{Multicol-break|2px}}
This text appears in the third column.
{{Multicol-end}}

The multi-column region is always positioned on the left side of the containing block. To change this, place the above Wikitext in a <tt>[[DIV (HTML tag)|DIV]]</tt> block that has the [[Cascading Style Sheet|CSS]] attribute <tt>text-align</tt> set to either <tt>center</tt> or <tt>right</tt>, like this:

<pre>
<div style="text-align:center;">{{center|
{{Multicol|50%|2px}}
...
{{Multicol-end}}
}}</div>
</pre>

== Related templates ==
The templates {{tl|Col-begin}} and friends do something similar to this template and its friends, but this template may be easier to use. Each of the following examples produce the same result (a 3-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 {{tk|Multicol-break}} and {{tl|Multicol-end}}, not {{tk|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 templates/others}}

<includeonly>
<!-- PLEASE ADD CATEGORIES BELOW THIS LINE, THANKS. -->
[[Category:Table and column templates]]
</includeonly>