From Meta, a Wikimedia project coordination wiki
Jump to: navigation, search
MediaWiki Handbook: Contents, Readers, Editors, Moderators, System admins, Researchers +/-

A page can be divided into sections, using the section heading syntax.

Creation and numbering of sections[edit]

Sections are created by creating their headings, as below:




Headers with only one equals sign on a side (=text here=) causes a title the size of the page name. On Wikimedia wikis they are used only sparingly and in prescribed circumstances.

When you create a section header, you can't have other content on the same line. For example ==Section Header==<br> will not work.

With the preference setting Auto-number headings section numbering appears at each heading.

Section names should preferably be unique within a page. This applies even for the names of subsections. Disadvantages of duplicate section names, even as subsections of different sections, include:

  • after section editing one confusingly arrives at the wrong section; see also below.
  • the automatic edit summary on editing a section is ambiguous

A section (or sections) of a page can be an included separate page (or template), without changing the appearance of a page. See Help:Template#Composite_pages. This way a separate edit history is in effect provided for the section. Also this allows watching it separately.

In a page calling a template with sections, the sections in the template are numbered according to their position in the rendered page, e.g. if the template tag is in the third section, then the first section of the template is numbered four. Any text in the template before its first section shows up as part of the section with the template tag, and any text after the tag before a new heading shows up as part of the last section of the template. This may be done deliberately, but can usually better be avoided (see also below).

In MediaWiki, a section header in wikitext is defined by a regular expression, /(^={1,6}.*?={1,6}\s*?$)/m ("m" refers to multi-line mode).

Table of contents (TOC)[edit]

For each page with more than three headings, a table of contents (TOC) is automatically generated from the section headings, unless:

  • (for a user) preferences are set to turn it off
  • (for an article) the magic word __NOTOC__ (with two underscores on either side of the word) is added in the edit box

When either __FORCETOC__ or __TOC__ (with two underscores on either side of the word) is placed in the wikitext, a TOC is added even if the page has fewer than four headings.

With __FORCETOC__, the TOC is placed before the first section heading. With __TOC__, it is placed at the same position where this code is placed. This allows any positioning, e.g. on the right or in a table cell. In old versions of MediaWiki, it also allows multiple occurrence, e.g. in every section (However, this seems only useful if the sections are long, so that the TOCs take up only a small part of the total space.).

There may be some introductory text before the TOC, known as the "lead". Although usually a heading after the TOC is preferable, __TOC__ can be used to position the TOC correctly (i.e., not too low), rather than inserting a meaningless heading.

Using __NOTOC__ it is possible to disable the normal table of contents. Section links, as explained below, allow creating compact TOC's, e.g. alphabetical [[#A|A]] [[#B|B]] etc.


Word Explanation
__NOTOC__ Hides the ToC (table of contents) on the current page.
__FORCETOC__ Forces the ToC to appear.
__TOC__ Places a ToC here (overriding any __NOTOC__). Multiple ToCs are no longer supported. If __TOC__ is used multiple times, only the first occurence causes a ToC to appear.

Moving the table of contents[edit]

The Table of contents can be forced onto a floating table on the right hand of the screen with the code below:

  {| align="right"
  | __TOC__

Globally limiting the TOC depth[edit]

It is possible to limit the depth of sub-sections to show in the TOC globally using $wgMaxTocLevel. If configuration setting $wgMaxTocLevel in LocalSettings.php is set to 3 for example, only first and second level headings show up in the TOC. Until version 1.10.0rc1, there is a bug in the parser making a limited TOC display incorrectly. A simple solution is proposed in bug report 6204.

Hidden comments[edit]

To make hidden comments, add the HTML <!-- tag, type what you want to hide, then end it with --> , like this:


The HTML standard calls for a space character between the tags and the text. Many browsers accept the tags without the spaces, but you're safest using them for full compatibility.

Hidden comments are used mainly as notices to people editing a page. MediaWiki supports this HTML, so you can use this code on this or any other MediaWiki wiki as well as in building your own website.

Section linking[edit]

In the HTML code for each section there is an "id" attribute holding the section title. This enables linking directly to sections. These section anchors are automatically used by MediaWiki when it generates a table of contents for the page, and therefore when a section heading in the ToC is clicked, it will jump to the section. Also, the section anchors can be manually linked directly to one section within a page.

The HTML code generated at the beginning of this section, for example, is:

<h2><span class="mw-headline" id="Section_linking">Section linking</span></h2>

A link to this section (Section linking) looks like this:

[[Help:Section#Section_linking|Section linking]]

To link to a section in the same page you can use [[#section name|displayed text]], and to link to a section in another page [[page name#section name|displayed text]].

The anchors disregard the depth of the section; a link to a subsection or sub-subsection etc. will be [[#subsection name]] and [[#sub-subsection name]] etc.

An underscore and number are appended to duplicate section names. E.g. for three sections named "Example", the names (for section linking) will be "Example", "Example_2" and "Example_3". However, after editing section "Example_2" or "Example_3" (see below), one, confusingly, arrives at section "Example" from the edit summary. For a workaround, see #Linking to a specific place in the text.

If a section has a blank space as heading, it results in a link in the TOC that does not work. For a similar effect see NS:0.

Section linking with arbitrary id[edit]

Unfortunately, section link anchors can change invisibly. If an article has several (sub)sections with the same name, their links will be distinguished by " 2", " 3", and so on added at the end of all but the first. If you link to the third section with a particular name, and someone later adds (or deletes or renames) a section with the same name above that one, the link you made will point to the wrong section, or one that doesn't exist.

You can avoid this with the HTML span tag with the id attribute:

<span id="anchor_name"></span>

Be sure to use a name that is not likely to be duplicated. One way to do this is to incorporate the titles of the higher-level sections, at least in abbreviated form, e.g., Ontario-Natural_features for the "Natural features" subsection of the "Ontario" section of an article about the provinces of Canada. (This example is made-up, but the principle applies.) Sadly, this won't work with some very old browsers. In some older versions of Mediawiki (at least in 1.4.10), it won't work even with new browsers if the id has a space in it. For example:

<span id="Ontario-Natural features">(optional text)</span> [won't work]
<span id="Newfoundland-Natural_features">(optional text)</span> [will work]
See [[#Ontario-Natural features|natural features of Ontario]]'' and ''[[#Newfoundland-Natural features|natural features of Newfoundland]].

If the id has spaces, links to it will not work. Change the spaces to underscores in the id, and the link will work with either underscores or spaces, as expected.


For linking to an arbitrary position in a page see manual anchors.

Section linking and redirects[edit]

A link that specifies a section of a redirect page corresponds to a link to that section of the target of the redirect.

A redirect to a section of a page may also work in some environments (see bug 218), try e.g. the redirect page Section linking and redirects. (One might have to force reload CSS style sheets.)

A complication is that, unlike renaming a page, renaming a section does not create some kind of redirect. Also there is no separate backlink feature for sections, pages linking to the section are included in the list of pages linking to the page. Possible workarounds:

  • Instead of linking directly to a section, link to a page that redirects to the section; when the name of the section is changed, change the redirect target. This method also provides more or less a "what links here" for sections (look for redirects linking to the page, select the one linking to the section; this may be recognized from the name even if the section name has changed).
  • Put an anchor and link to that
  • Put a comment in the wikitext at the start of a section listing pages that link to the section
  • Make the section a separate page/template and either transclude it into, or just link to it from, its parent page; instead of linking to the section one can then link to the separate page.

Redirect pages can be categorized by adding a category tag after the redirect command. In the case that the target of the redirect is a section this has to some extent the effect of categorizing the section: through the redirect the category page links to the section; however, unless an explicit link is put, the section does not link to the category. On the category page redirects are displayed with class redirect-in-category, so they can be shown in e.g. italics; this can be defined in MediaWiki:Common.css. See also w:Wikipedia:Categorizing redirects redirects.

Section editing[edit]

Sections can be separately edited by clicking special edit links labeled "[edit]" by the heading, or by right clicking on the section heading, depending on the preferences set. This is called "section editing feature". Section editing feature will take you to an edit page by a URl such as


Note that here section numbers are used, not section titles; subsections have a single number, e.g. section 2.1 may be numbered 3, section 3 is then numbered 4, etc. You can also directly type in such URL's in the address bar of your browser.

This is convenient if the edit does not involve other sections and one needs not have the text of other sections at hand during the edit (or if one needs it, open the section edit link in a new window, or during section editing, open the main page in a different window). Section editing alleviates some problems of large pages.

"__NOEDITSECTION__" anywhere on the page will remove the edit links and disable editing by right-clicking on the section heading. It will not disable section editing itself: the URL for that still works.

Inserting a section can be done by editing either the section before or after it, merging with the previous section by deleting the heading. Note that in these cases the preloaded section name in the edit summary is not correct, and has to be changed or deleted.

Adding a section at the end[edit]

Adding a section at the end can also be done with a URL like // On talk pages and pages with in the wikitext the code __NEWSECTIONLINK__ a special link labeled with the message with id 'addsection' (talk), e.g. "+" or "Post a new comment", is provided for this. In this case, a text box with as title the message with id 'subject' (talk), e.g. "Subject/headline", will appear and the content you type in it will become the section heading. There is no inputbox for the edit summary, it is automatically created according to the pattern of message with id 'newsectionsummary' (talk), where "/* $1 */" represents a right arrow linking to the new section and, with CSS-class "autocomment", the name of the section followed by " - ". In the case of the default of message newsectionsummary this is followed by the text "new section". The user cannot provide more text for the edit summary than just the header itself (use the method mentioned earlier if that is desired).

Parameter "preloadtitle" provides initial content of the "Subject/headline" box, e.g.:


It can be edited before saving.

The &section=new feature is commonly used to create a new section, with a title given from the "Subject/headline" box, but the engine does not create a new section if the subject box was left blank – no empty == == delimiter is inserted. Without a subject given, a wikitext is simply appended to the page (say, to its last section). Note that this does not preclude a section creation, as wikitext may contain such delimiters at it own (such as ==Section==, ===Section=== or so). Operating the &section=new feature without a subject is not recommended because there exists no way to provide an edit summary.

Editing before the first section[edit]

In general, no particular link for editing the introductory text before the first section heading is provided (bugzilla:156). However, section editing feature can also be applied to this part by giving 0 as the section number such as // . A less cumbersome way to obtain this link is to use any section edit link of the page, and change the number of the section to zero.

Javascript can also create this URL, see w:Wikipedia:WikiProject User scripts/Scripts/Edit Top.

The {{Edit-first-section}} and {{Edit-top-section}} templates create an edit link for the section 0. Each is positioned slightly differently. Copy these templates to your wiki. (Note: These are not available on the English Wikipedia due the availability of "Special:Preferences > Gadgets > User Interface Gadgets".)

See also Help:Section editing demo.


The preview in section editing does not always show the same as the corresponding part of the full page, e.g. if on the full page an image in the previous section intrudes into the section concerned.

The edit page shows the list of templates used on the whole page, i.e. also the templates used in other sections.


Subsections are included in the part of the section that is edited. Section numbering is relative to the part that is edited, so on the relative top level there is always just number 1, relative subsections all have numbers starting with 1: 1.1., 1.2, etc.; e.g., when editing subsection 3.2, sub-subsection 3.2.4 is numbered 1.4. However, the heading format is according to the absolute level.

Editing a page with large sections[edit]

If a page has very large sections, or is very large and has no division into sections, and one's browser or connection does not allow editing of such a large section, then one can still:

  • append a section by specifying a large section number (too large does not matter); however, one has to start with a blank line before the new section heading
  • append content to the last section by not starting with a section heading; however, with the limitations of one's browser or connection, one cannot revert this, or edit one's new text.

If one can view the wikitext of a large section, one can divide the page into smaller sections by step by step appending one, and finally deleting the original content (this can be done one large section at a time). Thus temporarily there is partial duplication of the content, so it is useful to put an explanation in the edit summary.

Editing sections of included templates[edit]

The section editing feature can also be applied to a section of an included page or template. When clicking the edit link of the section that is transcluded, the link target will be the edit page of the separate page. This section, Help:Editing sections of included templates, is an example.

For the purpose of section editing the extent of a section is governed by the headings in the calling page itself. If there is a text before the first section heading of the separate page, this will appear as a part of the section of the parent page that includes the template tag, but clicking its section edit link will not show the wikitext of the separate page. Or if there is a text after the template tag without a specific section heading, to edit this text with section edit feature, one has to click the section headings preceding the template tag.

Therefore it tends to be confusing if the extent of sections in the rendered parent page is different from what the actual wikitext contains. To avoid this:

  • if a template has headings, do not put any text before the first heading
  • in the calling page, start a new section after a template that itself has sections

It may be convenient, where suitable, to start a template with a section heading, even if normally the contents of the template would not need a division into sections, and thus the template is only one section. The section editing feature can then be used for editing the template from a page that includes it, without specially putting an edit link. This template is an example, it does not need a division into sections, but has a heading at the top.

Note that a parameter value appearing in a template, for example "{{{1}}}", is not edited by editing the template but by editing the template tag in the calling page, even though the rendered page and its edit links do not automatically show that. Some explanatory text and/or an extra edit link can be useful.

The __NOEDITSECTION__ tag in any template affects both that template, the pages it's included on, and any other templates included on the same page. A workaround for this issue is described in phab:T48940: it is possible avoid the need to use __NOEDITSECTION__ in a template by to forcing the template to not recognize section headers as editable. Replacing mediawiki section header markup (surrounding headers with == markers to the desired depth) in the template with HTML header markup (surrounding headers with <h1></h1> tags, changing "1" to the desired depth) will result in headers visually identical to the first style, both on the template page and when transcluded, but which are not treated as editable sections.

For example, imagine a template called MyTemplate, containing the following:

==Template heading 1==
===Template heading 2===

Transcluding MyTemplate into another page will result in "edit section" links appearing after Template heading 1 and Template heading 2 on the page the template is transcluded into, which is often undesirable. Adding __NOEDITSECTION__ anywhere within the code of MyTemplate will result in suppression of these "edit section" links within the template, but also everywhere on pages it is transcluded into. If, however, MyTemplate contains the following rather than the above:

<h2>Template heading 1</h2>
<h3>Template heading 2</h3>

then the headings will be visually identical to the previous output of MyTemplate, except that they will not be accompanied by "edit section" links. Section headings elsewhere on pages where MyTemplate is transcluded will be unaffected, and abide by whatever the page's "edit section" settings are.

Sections within parser functions[edit]

When conditionally (using a parser function) transcluding a template with sections, edit links of this and subsequent sections will edit the wrong section or give the error mesage that the section does not exist (although the page (including TOC) is correctly displayed and the TOC links correctly). This is because for the targets of the edit links the content of conditionally included templates is considered part of the page itself, and the sections are counted after expansion.

Thus the edit links of the sections of the included template link to the page itself instead of the template, and the edit links after the included template link to the correct page but the wrong section number.

More generally conditional sections give such a complication.

The problem does not occur when transcluding a template with a conditional name (which has more advantages). Use Template:Void for the template to transclude to produce nothing.

Editing a footnote[edit]

To edit a footnote rendered in a section containing the code <references />, edit the section with the footnote mark referring to it, see Help:Footnotes.

Viewing a section[edit]

The section editing feature can also be used to just view a section without loading the whole page. There is no other way.

Sections vs. separate pages vs. transclusion[edit]

Advantages of separate pages:

  • what links here feature
  • separate edit histories
  • some template limits apply per page
  • automatic redirect on renaming
  • loading a small page is faster than loading a large page
  • can separately be put in categories (however, see also below)
  • with Semantic MediaWiki: have separate annotations

Advantages of one large page with sections:

  • loading one large page is faster and more convenient than loading several small ones
  • searching within one large page (the page itself or the wikitext) with a local search function is faster and in some respects better than searching several pages (for which one has to search the whole project); also the TOC provides for convenient navigation.
  • enforces the cohesion of a concept that while having several definitions needs independent editing.

An alternative is composing a page of other pages using the template feature (creating a compound document by Transclusion). This allows easy searching within the combined rendered page, but not in the combined wikitext. As a disadvantage, a title for each page has to be provided. For the pre-expand include size limit this is disadvantageous even compared with one large page: the pre-expand include size is the sum of the pre-expand include sizes of the components plus the sum of sizes of the wikitexts of the components.

Sections and TOC[edit]

Making a heading that does not show up in ToC[edit]

In some older versions, if you didn't want a heading to show up in the generated Table of Contents at the top of the page, you could use HTML to make the heading.

<h2>A level-2 heading that shouldn't show up in the TOC</h2>

But that no longer is supported; by design, HTML headings now show up in the TOC no matter what; see the discussion at

A simple extension can give you the ability to create non-TOC headings. Try the following, which was written using instructions from Extending wiki markup:

# H3ForCommentsButNotInTOC.php
# Example WikiMedia extension  
# with WikiMedia's extension mechanism it is possible to define
# new tags of the form
# <TAGNAME> some text </TAGNAME>
# the function registered by the extension gets the text between the
# tags as input and can transform it into arbitrary HTML code.
# Note: The output is not interpreted as WikiText but directly
#       included in the HTML output. So Wiki markup is not supported.
# To activate the extension, include it from your LocalSettings.php
# with: include("extensions/YourExtensionName.php");

$wgExtensionFunctions[] = "wfH3ForComments";

function wfH3ForComments() {
    global $wgParser;
    # register the extension with the WikiText parser
    # the first parameter is the name of the new tag.
    # In this case it defines the tag <example> ... </example>
    # the second parameter is the callback function for
    # processing the text between the tags
    $wgParser->setHook( "xh3", "renderxh3" );

# The callback function for converting the input text to HTML output
function renderxh3( $input, $argv, &$parser ) {
    $output = "<h3>$input</h3>";
    return $output;

Then of course you have to install the extension by adding the following to LocalSettings.php:


To add an <h3> heading that won't show up in the TOC, do it as:

<xh3>Text for an h3 heading that won't be in the TOC</xh3>

This is pretty crude, and only provides for an H3-level heading. Perhaps someone who actually knows PHP (instead of doing monkey-see-monkey-do programming like I just did) could add code to create tags for H1, H2, and H4.

UPDATE: To add it for all HTML heading levels, handle nested wikitext, and also avoid the cross-site scripting/HTML injection vulnerability (outputting untrusted user input as HTML), the following will do:

# HeaderNotInTOC.php
# To activate the extension, include it from your LocalSettings.php
# with: require_once( "$IP/extensions/HeaderNotInTOC.php" );

$wgExtensionFunctions[] = "wfHeaderNotInTOC";
function wfHeaderNotInTOC() {
    global $wgParser;
    # register the extension with the WikiText parser
    # the first parameter is the name of the new tag.
    # the second parameter is the callback function for
    # processing the text between the tags
    $wgParser->setHook( "xh1", "wfHeaderNotInTOCxh1" );
    $wgParser->setHook( "xh2", "wfHeaderNotInTOCxh2" );
    $wgParser->setHook( "xh3", "wfHeaderNotInTOCxh3" );
    $wgParser->setHook( "xh4", "wfHeaderNotInTOCxh4" );
    $wgParser->setHook( "xh5", "wfHeaderNotInTOCxh5" );
    $wgParser->setHook( "xh6", "wfHeaderNotInTOCxh6" );

# Helper function to output headings
function wfHeaderNotInTOCparse($input, $level, $parser)
    return "<h$level>" . $parser->recursiveTagParse($input) . "</h$level>";
# The callback functions for converting the input text to HTML output
function wfHeaderNotInTOCxh1( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 1, $parser);
function wfHeaderNotInTOCxh2( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 2, $parser);
function wfHeaderNotInTOCxh3( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 3, $parser);
function wfHeaderNotInTOCxh4( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 4, $parser);
function wfHeaderNotInTOCxh5( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 5, $parser);
function wfHeaderNotInTOCxh6( $input, $argv, $parser ) {
    return wfHeaderNotInTOCparse($input, 6, $parser);

Making text show up in TOC that is not part of a formal section title[edit]

Text that is not part of a section title, can be forced to be interpreted as a TOC entry, by wrapping it in header tags such as <h4>...</h4>. Within the header tags, formatting can be set or customized as usual. Example usage (the second example has additional formatting fixes for reference):

{| class="navbox collapsible collapsed" style="text-align: left; border: 0px; margin-top: 0.2em;"
! style="background-color: #f2dfce;" | <h4>Stuff</h4>
| Contents about stuff here

{| class="navbox collapsible collapsed" style="text-align: left; border: 0px; margin-top: 0.2em;"
! style="background-color: #f2dfce;padding-top:0;padding-bottom:0" |
 <h4 style="margin:0; padding:0;font-size:95%">More stuff</h4>
| Contents about more stuff here

treats the header of the collapse boxes as section titles, adds them to TOC, but does not create or require formal "section titles" to exist in the page itself.

Although highly non-recommended, it is also possible to create a TOC entry that does not appear in the article text, but will still act correctly as an anchor (for example, to follow it with a section header of slightly different wording):

<h4 style='display: none'>Your heading here</h4>

Hiding the Main page heading at the top[edit]

Add this code to YourLanguage:MediaWiki:Common.css (substituting NameOfYourPage for the correspondent translation into your language:

.page-NameOfYourMainPage .firstHeading { display:none; }

Sections for demo above[edit]

Demo abc[edit]

This section is linked to from #Section linking.

Demo http://a[edit]

This section is linked to from #Section linking.

Section size policies[edit]

The size of sections may vary, depending on what kind of subject is described and other variables. "Hard" knowledge, e.g. biochemistry articles, presenting many names and mechanisms in a short interval may have shorter section size, while, on the other hand, "soft" knowledge, like articles concerning movies, may have longer ones. There is no strict rule about how long a section may be, just as with wikipedia article size. Nevertheless, a proper section size is probably somewhere between 80 and 500 words. More specifically, "hard" knowledge articles should contain between 80 and 250, while "soft" ones may contain more than 250. Individual circumstances decides - many short sections makes it easier to find the desired information about a subject, but might, when used in excess, disturb the fluency of an article.

See also[edit]

Links to other help pages[edit]

Help contents
Meta · Wikinews · Wikipedia · Wikiquote · Wiktionary · Commons: · Wikidata · MediaWiki · Wikibooks · Wikisource · MediaWiki: Manual · Google
Versions of this help page (for other languages see further)
What links here on Meta or from Meta · Wikipedia · MediaWiki
Go · Search · Stop words · Namespace · Page name · Section · Backlinks · Redirect · Category · Image page · Special pages · Printable version
Tracking changes
Recent changes (enhanced) | Related changes · Watching pages · Diff · Page history · Edit summary · User contributions · Minor edit · Patrolled edit
Logging in and preferences
Logging in · Preferences · User style
Starting a new page · Advanced editing · Editing FAQ · Edit toolbar · Export · Import · Shortcuts · Edit conflict · Page size
Links · URL · Piped links · Interwiki linking · Footnotes
Style and formatting
Wikitext examples · CSS · Reference card · HTML in wikitext · Formula · List · Table · Sorting · Colors · Images and file uploads
Fixing mistakes
Show preview · Testing · Reverting edits
Advanced functioning
Expansion · Template · Advanced templates · Parser function · Parameter default · Variable · System message · Substitution · Array · Calculation · Embed page
Special characters · Renaming (moving) a page · Preparing a page for translation · Talk page · Signatures · Sandbox · Legal issues for editors
Languages: English · العربية · Deutsch · français · italiano · 日本語 · русский · shqip