Sections

Editor-In-Chief: C. Michael Gibson, M.S., M.D. [1]

overview

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

Creation and numbering of sections

Sections are created by creating their headings, as below:

==Section==

===Subsection===

====Sub-subsection====

Please do not use only one equals sign on a side (=text here=); this causes a title the size of the page name, which is taken care of automatically.

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

Section names can best 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).

Table of contents (TOC)

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 avoid being forced to insert a meaningless heading just to position the TOC correctly, i.e., not too low.

Using __NOTOC__ it is possible to disable the normal Table of Contents. Section links as explained below allow to create compact ToCs, e.g. alphabetical [[#A|A]] [[#B|B]] etc.

Summary: Template:H:TOC variables

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

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.

Section linking

In the HTML code for each section there is an anchor Template:H:mlw with both "name" and "id" attributes 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 you click a section heading in the ToC, you will jump to the section. You can also use section anchors to manually link directly to one section within a page.

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

<p><a name="Section_linking" id="Section_linking"></a></p>   
<h2>Section linking</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.

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.

To create an anchor target without a section heading, you can use a span, for example:
<span id="anchor_name"></span>, however this won't work with some very old browsers.

Note that using the date formatting feature in section headings complicates section linking.

An internal link in a section heading does not give complications in terms of section linkng:

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

Section linking and redirects

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 [2], try e.g. the redirect pageSection 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 inMediaWiki:Common.css. See also Template:Mlww.

Section editing

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 thepreferences set. This is called "section editing feature". Section editing feature will take you to an edit page by a URl such as

https://www.wikidoc.org/w/wiki.phtml?title=Help:Section&action=edit&section=2

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 URls 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. It will not disable section editing itself; right clicking on the section heading and the url still work.

Inserting a section can be done by editing either the section before or after it, merging with the previous section by deleting the heading.

Adding a section at the end can also be done with a URL like http://meta.wikimedia.org/w/wiki.phtml?title=Meta:Sandbox&action=edit&section=new . On talk pages a special link labeled "+" or "Post a new comment" is provided for this. In this case, a text box titled "Subject/headline" will appear and the content you type in it will become the section heading as well as the edit summary of the edit.

Editing before the first section

In general, no particular link for editing the introductory text before the first section heading is provided. However, section editing feature can also be applied to this part by giving 0 as the section number such as https://www.wikidoc.org/w/wiki.phtml?title=Help:Section&action=edit&section=0 . 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:en:Wikipedia:WikiProject User scripts/Scripts/Edit Top.

The {{Edit-first-section}} and {{Edit-top-section}}templates create an edit link for the section 0. Both are positioned slightly different. Copy these templates to your wiki.

Preview

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

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

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.

Help:Editing sections of included templates

Sections within parser functions

If a section heading is created conditionally using a parser function, either directly or by conditionally transcluding a template with sections, edit links of this and subsequent sections will edit the wrong section (although the page (including TOC) is correctly displayed and the TOC links correctly). This is because section counting for producing the edit links is done after expanding the parser functions, whereas when the edit page is loaded, only those sections are counted which statically appear in the page (or the respective template).

This is not a bug but a consequence of the way section editing is implemented, so the solutions are the obvious ones: either avoid creating sections via parser functions, or disable section editing.

Editing a footnote

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

Sections vs. separate pages vs. transclusion

Advantages of separate pages:

what links here feature
separate edit histories
the Template:Peisl applies 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 byTransclusion). 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.

Making a heading that does not show up in ToC

In some quite-older versions, if you wanted a heading not 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 http://bugzilla.wikimedia.org/show_bug.cgi?id=6575.

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

<?php
# 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:

require_once("extensions/H3ForCommentsButNotInTOC.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 H1, H2, H3 and H4, the following will do:

<?php
# HForCommentsButNotInTOC.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[] = "wfForComments";

function wfForComments() {
    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( "xh1", "renderxh1" );
    $wgParser->setHook( "xh2", "renderxh2" );
    $wgParser->setHook( "xh3", "renderxh3" );
    $wgParser->setHook( "xh4", "renderxh4" );
}

# The callback function for converting the input text to HTML output
function renderxh1( $input, $argv, &$parser ) {
    $output = "<h1>$input</h1>";
    return $output;
}
function renderxh2( $input, $argv, &$parser ) {
    $output = "<h2>$input</h2>";
    return $output;
}
function renderxh3( $input, $argv, &$parser ) {
    $output = "<h3>$input</h3>";
    return $output;
}
function renderxh4( $input, $argv, &$parser ) {
    $output = "<h4>$input</h4>";
    return $output;
}
?>