User:SMcCandlish/Manual of Style/Internal

Whitespace

The purpose of whitespace in code is generally to make it more readable to humans. Mediawiki has very few required (or forbidden) uses of whitespace, but it does add some complications:

• An entire blank line is interpreted as a paragraph break, and will generate <p>...</p> markup, even when this is inappropriate.
• Several features of MediaWiki only work at the beginning of a separate line. This includes heading markup (== ... ==, === ... ===, etc., which also cannot have any content after them on the same line), list markup (*, #, ;, and :), and table markup ({{|, |-, !, |, and |}). Some exceptions are table shorthand markup !! and || (used on the same line as an initial ! or |, respectively), and : which can follow ; on the same line.
• MediaWiki templates (what are called scripts in most other contexts) usually drop extraneous whitespace when parsing, but this is not true within the content passed as parameter values sometimes; it can take considerable experimentation to get this perfect. It also means that use of traditional code indentation in MW templates is "dangerous"; when it does not work as intended, it can generally be simulated by use of HTML comments across the line break, i.e. ending a line with <--, inserting the line break and indentation, then adding --> and continuing with the next line of code.
• A line break (directly entered, rather than coded inline with <br />) inside a list formatted with MediaWiki's own list-creation syntax (using *, #, ;, or :) breaks the list and starts a new one.
• The <code>...</code> element is styled in site-wide stylesheets with some padding-left. Consequently, traditional use of this element around entire multi-line blocks of code confusingly results in the first line being indented rightward. This can be fixed by using <code style="padding-left: 0;">...</code>
• There are various other "gotchas" that will be covered below, as needed.

Using two spaces or one after a sentence

Before beginning another sentence, whether to use a single space character or two after the terminal punctuation of the last sentence remains an ongoing and long-term controversy. Do not edit-war over this matter in any page, article or not. Do not make edits the sole or primary purpose of which is to futz with single- or double-spacing after a full stop (period).

The background of the conflict:

1. Style guides for generations have recommended double-spacing in typewritten manuscript materials for easier reading in a monospaced (non-proportional) font.
2. Modern style guides advise against this practice for proportionally typeset material, including documents produced in a word-processing application, because the rationale no longer applies.

The conflict exists on Wikipedia because some editors (especially those who do a significant amount of template coding) use a monospaced font in the editing pane, while others (mostly those who work on prose content while avoiding the more "geeky" aspects of wikiwork to the extent they can) use a proportional font. Neither side is universally "correct", though the latter side is apt to incorrectly cite usability and readability studies "proving" that single spacing is faster to read. This is novel and incorrect synthesis, because the studies to date have been of proportional-font material; none (As of 2017) have studied monospaced material and produced comparative data. Professional coders are almost universally in agreement that additional whitespace mades a notable difference in the ability of humans to quickly make sense of code, and it is unlikely that this view in favor of extra spacing could be so prevalent if were not correct with regard to monospaced material.

Definitely do not use more than two spaces.

Do not include any space characters at the end of a paragraph

This includes blocks of material that are not prose paragraphs, such as list items. If another content block or a blank line follows the block in question, do not put spaces after it.

Blank lines before and after headings

This is another area of dispute, though some best practices can be observed.

• Definitely include a blank line before a heading.
• Whether to include one after it or not is subject to editorial discretion.
  • The most common pattern is to include one after, unless what immediately follows is one or more hatnotes, dispute/cleanup templates, images, or similar non-prose, in which case this material takes the place of the blank line. (Although some editors have been including a blank after the last of these and before the "content proper" of the section, this can undesirably push the content downward.) Some editors prefer no blank line here at all.

Do not editwar about this.

Spaces inside headings

Yet another incompletely resolved dispute is whether to give headings in the style == Foo bar baz == versus ==Foo bar baz==.

• Preferable: == Foo bar baz == – The most common style in hand-edited code, and now also what VisualEditor does when creating a new heading. VE has no problem with either style, and since the former is more readable it is the de facto standard.
• Permissible: ==Foo bar baz== – Still common, and preferred by some editors. The readability hit is very minor.

Do not editwar about this.

Blank lines before and after lists, tables, block quotations, and other block elements

There is no requirement to separate block elements from preceding or following content with a blank line, but this is generally done unless that content is directly connected to the block in the narrative flow. For example, a block quotation might not have an entire blank line between it and an introduction like "According to Einstein:". Inserting one is harmless, however, and makes it easier to discern the presence of a block element, to more easily understand the paragraph structure of the document.

Regardless, consider at least a line break before and after the block content to be mandatory. In bare HTML markup, it is not required, but if someone converts that HTML to MediaWiki list or table markup, or to a template, there is a high likelihood that it will break if the block element does not begin and end on independent lines.

Blank lines between templates and the regular content

Entire blank lines are not done, however, with infoboxes, images, page- and section-top cleanup templates, disambiguation hatnotes, and other such markup claptrap. Just a line break between each and between the stack of them and the regular content is the necessary style, because extraneous blank lines in such material will push the visible content downward for no good reason. The top of an article should have no blank lines before the beginning of the content proper.

Example, from Fu Manchu:

{{about|the fictional character|the stoner-rock band|Fu Manchu (band)|other uses}} {{Multiple issues| {{refimprove|date=February 2012}} {{more footnotes|date=March 2013}} {{rewrite|date=October 2017}} }} {{Use British English|date=May 2013}} {{Use dmy dates|date=May 2013}} {{Infobox character |name = Dr. Fu Manchu |series = |image = Faceoffumanchu.jpg |caption = [[Film poster]] by [[Mitchell Hooks]] for 1965 film ''[[The Face of Fu Manchu]]'' |first = ''[[The Mystery of Dr. Fu-Manchu]]'' |last = ''Emperor Fu Manchu'' |creator = [[Sax Rohmer]] |portrayer = {{unbulleted list |Arthur Hughes |[[Harry Agar Lyons]] |[[Warner Oland]] |[[Boris Karloff]] |John C. Daly |[[Harold Huber]] |Frank Cochrane |[[Henry Brandon (actor)|Henry Brandon]] |[[Glen Gordon]] |[[Christopher Lee]] |[[Peter Sellers]] |[[Nicolas Cage]] }} |gender = Male |occupation = [[Mad scientist]], [[supervillain]] |nationality = Chinese }} '''Dr. Fu Manchu''' is a fictional [[villain]] character introduced in a series of novels by British author [[Sax Rohmer]] during the first half of the twentieth century. The character was also featured extensively in cinema, television, radio, comic strips, and comic books for over 90 years, and has become an [[archetype]] of the [[Supervillain|evil criminal genius]] and [[mad scientist]], while lending the name to the [[Fu Manchu moustache]]. [Rest of article here.]

Use <br /> correctly

When inducing a line break with the HTML element <br />, do not include space characters before or after it; these are useless.

Do not give it as "<br>", "<br/>", or truly mangled formulations like "</br>". This just creates pointless cleanup work for others to do, and can break the syntax highlighting many editors rely on.

For lists, use a proper list; do not create pseudo-lists with <br />. Lists are normally done with regular list markup. For special cases like use in infoboxes, you can use a template like {{plainlist}} or {{Unbulleted list}} (no bullets or indentation), or {{Flatlist}} or {{Hlist}} (inline on the same line and separated by · characters).

For paragraphs, use real paragraph markup. This is usually just done with a blank line (which the MediaWiki parser turns into a properly marked-up paragraph start tag for the content the follows it. It can also be done with explicit <p>...</p> markup in cases that require this, such as inline in a list item in a list that uses basic MediaWiki markup, e.g.: * Start of list item.<p>Second paragraph of list item.</p>

Include a line break in the code, when you can, where one will be visible to readers

Whenever technically possible, include a line break (a CR/LF, i.e., press ↵ Enter or Return) in the markup where ever one will be visible to readers in the rendered output of most browsers. This greatly helps editors find and edit the specific bit of content they are looking, and helps preview the eventual structure of the content without having to actually load a rendered preview of the page.

For example, put a line break in the wikicode after a <br />, before and after block elements, and so on. Another example:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<blockquote>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</blockquote>
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

This example uses raw HTML, but it also applies to templates like {{Blockquote}}. Some templates will actually fail if this is not done, such as {{Collapse bottom}} and many similar block-termination templates.

A third example is the use of templates like {{Unbulleted list}}. While it is possible to do them in the form {{Unbulleted list |Item 1 |Item 2 |Item 3 |...}}, this is very unhelpful for other editors. Use the following style instead, to make it immediately clear that a list is present and that it is one:

{{Unbulleted list
 |Item 1
 |Item 2
 |Item 2
 |...
}}

Exception: Line breaks within list items

This in-source linebreaking cannot be done within any item in a simple wiki-markup list (a list using *, #, or ; and : markup). All elements within such a list-item must be inline on the same line as the rest of the item, or the list will break. (For details, see Help:List § Paragraphs and other breaks; you can use inline HTML on the same line to introduce line and paragraph breaks, or use HTML or templated HTML wrappers for the entire list.) These lists also cannot include blank lines between list items (see Wikipedia:Manual of Style/Accessibility § Lists).

Citation templates should be given in horizontal format in regular text, but in vertical format in blocks of citations at the end

A horizontal templated citation looks like this:
     {{Cite book|last=Persson |title=Advanced Underwater Basketweaving |date=2024 |publisher=Aquatic Weavers' Association}}

A vertical citation looks like:

{{Cite book
|first=Guy
|last=Persson
|title=Advanced Underwater Basketweaving
|date=2024
|publisher=Aquatic Weavers' Association
}}

Using vertical citations in regular text makes it difficult for editors to discern the paragraph structure and the relative size and complexity of a paragraph; one with numerous vertical citations with a large amount of source data can fill many screens of text. On the other hand, vertical citations are much easier to read in a "References" section devoted to nothing but citation data, where prose paragraphs do not exist. (For details see list-defined references a.k.a. WP:LDR).

Spacing of template parameters

A solid consensus has not emerged on the matter, but a de facto consensus is very clearly observable in practice:

• Short templates should generally be given without spaces, unless hard to read in this format: ''{{lang|la|ars gratia artis}}''
• Longer, detailed templates – especially citation templates, arguably our most important, most frequently reviewed and edited, and most essential to get correct – should be spaced in horizontal format:
  • The most common format: {{Cite book |first=Guy |last=Persson |title=Advanced Underwater Basketweaving |date=2017 |publisher=Aquatic Weavers' Association}} – Clearly groups parameters and their values.
  • Also common, but disfavored as overkill by many: {{Cite book |first= Guy |last= Persson |title= Advanced Underwater Basketweaving |date= 2017 |publisher= Aquatic Weavers' Association }} – An argument has been offered that this is more accessible for both the visually impaired and those using small displays, as on mobile devices. However – as with coder preferences for double-spacing after a sentence – there isn't any reliable-source evidence for this yet.
    Either of these formats, when it comes to individual parameters, can also be used in vertical citations, infoboxes, and other templates.
• Several formats are not helpful and should not be used:
  • {{Cite book | first = Guy | last = Persson | title = Advanced Underwater Basketweaving | date = 2017 | publisher = Aquatic Weavers' Association }} – Serves no purpose, is visually confusing, and causes unhelpful line wrapping between parts of the parameter ID (the |, the parameter name, and the =).
  • {{Cite book| first=Guy| last=Persson| title=Advanced Underwater Basketweaving| date=2017| publisher=Aquatic Weavers' Association}} – Worse yet, adheres the starting character of the next parameter to the value of the last; this creates clumping of code that doesn't correspond to anything meaningful.
  • {{Cite book| first= Guy| last= Persson| title= Advanced Underwater Basketweaving| date= 2017| publisher= Aquatic Weavers' Association}} – Ditto.
  • {{Cite book| first =Guy| last =Persson| title =Advanced Underwater Basketweaving| date =2017| publisher =Aquatic Weavers' Association}} – Ditto.
  • {{Cite book| first = Guy| last = Persson| title = Advanced Underwater Basketweaving| date = 2017| publisher = Aquatic Weavers' Association}} – Ditto.
  • {{Cite book|first=Guy|last=Persson|title=Advanced Underwater Basketweaving|date=|publisher=Aquatic Weavers' Association}} – Run-together and difficult to understand; makes it easy to accidentally insert conflicting parameters (e.g., two |date= parameters), and hard to notice that a parameter is empty (did you notice, in that example?).
• Do insert a space between |parameter_name= and a long, unbroken value, such as URLs: |url= https://wayback.archive.org/web/20171219034128/https://www.eff.org/... – Allows the line to break just before the long string.

Empty template parameters: Remove empty template parameters unless:

• A present but no-value parameter has a special meaning in the template in question (few templates are coded this way any longer; in more than 99% of cases a parameter being missing or being there but empty has the same effect).
• It is a parameter that definitely should be filled because the information is required or important, but the data simply unavailable to the present editor.

Template documentation often includes copy-paste blocks of empty code to fill in. Doing this without removing dead-code parameters that will never be filled makes a mess. Worse, especially for infoboxes, it can encourage inexperienced editors to try to fill unnecessary or inappropriate parameters, often without reading the documentation to find out what the parameters are for and what form their input must take.

CSS should be readably spaced: When giving raw CSS directives, either space them out completely or clump them by directive:

• Readable: margin-left: 1.5em; padding-left: 2em;
• Less readable: margin-left:1.5em; padding-left:2em;
• Headache:margin-left:1.5em;padding-left:2em;

Some quick reminders: Numbers and units must be fused together in CSS (2em). Close the final or only directive with a semicolon (;), to prevent errors if someone adds another later and doesn't notice the character is missing. Multi-word values must be single-quoted, and they must be separated by commas when there's more than one (font-family: 'Lucida Grande', sans-serif;). Different types of values in shortcut properties must be separated by spaces (border: 1px solid LightGrey;), as must class names (class="hatnote navigation-not-searchable").

Links and anchors

Remember that these features exist and are used for navigation from content to more content.

Anchors below or inside headings

Subject to ongoing dispute for several years. The nature of the dispute:

1. Anchors below headings take readers who follow links to the line on which the anchor appears, in most cases and in most browsers. Some consider this a problem, because the heading above the anchor is usually not visible.
2. Putting the anchor, in any form, in the heading inserts junk code into the edit summary, and depending on exact code can also make a mess of edit history, and even (if there's a coding error) the visible table of contents.
3. The "obvious" solution, of putting the anchor immediately above the heading, separates the anchor from the section to which is pertains, and will cause the anchor to no longer take people to the right section if a later editor reorganizes sections in the page and doesn't notice and move the out-of-section anchors to match.

The overwhelmingly most common practice in mainspace is to include anchors below headings, not inside them, to avoid confusing new editors with mangled edit summaries.

Outside articles, some editors are adamant about including anchors, somehow, inside the headings, while others are dead-set against this. See WP:Manual of Style/Accessibility/anchor tests for test cases of every known style and what it does; this has not yet been tested with screen readers, many mobile browsers, and various other scenarios. Do not editwar about it, but prefer below the heading by default, as least likely to be problematic.

Linking to Wikipedia pages

• A piped link to a "Wikipedia:" page should always give the full name of the page (Wikipedia:Neutral point of view) and, if applicable, section (Wikipedia:Neutral point of view#Balance). At very least, use the "WP:" version with the full page name (WP:Neutral point of view). This link should go to the real page, not a redirect. Using a shortcut like WP:NPOV here is "reader-hateful", since the point is for them to get a clear indication of the name of the link target when the mouse pointer or other focus is over the link.
• An in-text link in "Wikipedia:" (or similar, e.g. "Help:") page to another one should use the "WP:" version (WP:Neutral point of view) for brevity. Even new users figure out within moments first starts to read such pages that "WP" is short for "Wikipedia". You can use the {{section link}} parameter to produce less geeky output: {{section link|WP:Neutral point of view#Balance}} produces: WP:Neutral point of view § Balance.
• Shortcuts (WP:NPOV, MOS:BIO) are for editors' typing convenience in talk-page and notice-board discussions, and should not usually be used in advice materials, nor in piped links. An obvious exception is a form like: {{section link|WP:Neutral point of view#Balance}} ([[WP:BALANCE]]) – part of how we educate new users what all these shortcuts are. Remember that our policy, guideline, help, essay, and information pages are primarily intended for new users, not the old hands who have memorized and helped write them, so use of shortcuts in them as if they're already understood defeats the purpose.
• In the rare event of a mainspace link to a "Wikipedia:" page (e.g., in an article about Wikipedia itself, or in a disambiguation hatnote at the top of an article), always use the full name of the real page, without any abbreviation or redirecting: Wikipedia:Neutral point of view.

Piped links

Piped links should be done in the most concise manner, e.g. [[cheese ball]]s not [[Cheese ball|cheese balls]].

It is not necessary to bypass every redirect, and doing so may be undesirable, especially if a future article might be created. E.g. if Papageno exists as a redirect to The Magic Flute, then just use [[Papageno]], not [[The Magic Flute|Papageno]]. (For more information, see Wikipedia:Redirect § Do not "fix" links to redirects that are not broken.)

Do not remove the capital letter from the article name at the start of a piped link. The format [[List of horse breeds|breed of horse]] is easier to instantly understand as a piped link any time the lead word of the article title is not a proper name; the capitalization is itself a "this is a piped link" indicator. It also helps find incorrectly capitalized links that are not piped, as in "He later became a [[Chicken]] farmer." Any such capitalized link should be at the start piped, a proper name, or at the start of a sentence. When the page is veering back and forth between things like [[Chicken|rooster]] and [[chicken|hen]] this visual cleanup scanning becomes more difficult.