TextFormattingRules

Last edit

Summary: New markup feature: \\ creates a line break.

Changed:

< [:Lists]

to

> [:Lists][:Bullets]

Added:

> See [[#ListIndentation|Indentation]] for how to add a separate paragraph (or a line break) to a list item (i.e., at the same indentation level).
> [:indendation]
> == Indentation ==
> * Indented lines start with one or more colons, followed by one or more whitespace characters [space or tabs]
> * ('##: ##') -- more colons mean more indention.
> * Indented lines must be the first sentence in a paragraph.\\
> (This is useful for personal replies or blockquotes. See also [[#Dialog]].)
> [:ListIndentation]
> * You can use two backslashes '''##\\##''', to insert a line break at the current indentation level. The previous list item shows an example: ##\\## is used between ##paragraph.## and ##(This is useful##.\\\\
> To create the appearance of a separate paragraph (like this one) within a list item, you can use '''##\\\\##'''.

Deleted:

< [:indendation]
< == Indentation ==
< * Indented lines start with one or more colons, followed by one or more whitespace characters [space or tabs]
< * ('##: ##') -- more colons mean more indention.
< * Indented lines must be the first sentence in a paragraph.
< * (This is useful for personal replies or blockquotes. See also [[#Dialog]].)


How do you learn to format Wiki pages?

Basics

Generally, it is important to use as little markup as possible:

  1. It makes the “source code” easier to read and modify.
  2. On the other hand, we also want to make the text easy to read.
  3. This sometimes calls for making things stand out.
  4. These two goals can sometimes conflict.

These are the most important formatting rules:

The official documentation is here:

Alternative Markup

The basic punctuation-based markup (see above) is preferable in all cases where it works. Alternative markup works in some additional contexts.

Wiki Tags

The following markup tags have special effects on this wiki. Use them like HTML tags.

<code>
Code (usually monospaced, plus escaping of wiki processing): <code>foo</code> → foo
<nowiki>
No wiki processing (usually to unlink mixed case words): <nowiki>[[No Link]]</nowiki> → [[No Link]]
<pre>
Preformatted (usually monospaced, for paragraphs, plus whitespace is preserved, plus escaping of wiki processing). <pre> tags must be alone on a line, to work. Example: to produce a line with foo, use this:
        <pre>
        foo
        </pre>

HTML Tags

The following standard HTML tags can be used on the wiki. Use them like HTML tags.

<u>
underline: <u>foo bar (toto)</u> → foo bar (toto)
<i>
Italics: <i>foo bar (toto)</i> → foo bar (toto)
<b>
Bold: <b>foo bar (toto)</b> → foo bar (toto)
<tt>
Teletype (usually monospaced): <tt>foo bar (toto)</tt> → foo bar (toto)
<em>
Emphasis (usually italics): <em>foo bar (toto)</em> → foo bar (toto)
<strong>
Strong (usually bold): <strong>foo bar (toto)</strong> → foo bar (toto)

BBCode

“BBCode is an abbreviation for Bulletin Board Code, the lightweight markup language used to format posts in many message boards. The available tags are usually indicated by rectangular brackets surrounding a keyword, and they are parsed by the message board system before being translated into a markup language the web browsers understands, usually HTML or XHTML” – Wikipedia

[b]this text is bold[/b]
[i]this text is italic[/i]
[u]this text is underlined[/u]
[s]this text is striked through[/s] [strike]and this too[/strike]
[tt]monospaced text[/tt]
[sub]subscript[/sub] [sup]superscript[/sup]
[color=blue]this text is blue[/color]
[size=+2]this text is two sizes larger than normal[/size]
[font=courier]this text is in the courier font[/font]
[quote]quoted text[/quote]
[code]preformatted monospaced text[/code] (no nesting of other bbCode!)
[center]this text is centered[/center]
[img]http://www.example.org/logo.png[/img]
[left]this (often an image) floats left[/left]
[right]this (often an image) floats right[/right]
[h1]title[/h1]
[h2]title[/h2]
[h3]title[/h3]
[h4]title[/h4]
[h5]title[/h5]
[h6]title[/h6]
[list]
  [*]item one
  [*]item two
[/list]
:) :-) ☺ (smile)
:( :-( ☹ (frown)

Note that traditionally, [url‍=http://www.example.org/]text[/url] would also be allowed. Apparently spammers also like it, which is why it ended up on BannedRegexps.

Links and Anchors

Wiki actions

The reflexive intermap-link EmacsWiki has some of the following actions:

A more complete list can be found at http://www.oddmuse.org/cgi-bin/oddmuse/Action_List

Lists

Lists and indented paragraphs start with a special character followed by at least one space character. For example, a bulleted list item starts with ‘* ’, not with just ‘*’.

  1. A numbered list is an ordered list that uses numbers sequentially as labels. List items start with a pound sign (`#’).
  2. second item
    1. ordered sublist (with `##’)
  3. etc.
Definition list
A definition list is a list with text labels. Items in definition lists start with a semi-colon (`;’) and a space (see above), followed by any amount of text, and the description starts with a colon (’:’). Your syntax should look like this:
           ; Term: Description.
Example
This list is an example of definition list
Third item
and its definition

See Indentation for how to add a separate paragraph (or a line break) to a list item (i.e., at the same indentation level).

Indentation

Tables

For tabular information that doesn’t fit in lists or definition lists, use tables.

For example, this table has two columns, with the second row having an empty first column, and the third and final column spanning all the rows.

||First row||||Second column||
|| ||Not empty||
||||Span the columns||

Becomes:

First rowSecond column
Not empty
Span the columns

Official documentation is at Oddmuse:Table Markup Extension.

Dialog ([new])

Conversation should be separated with [new] on a line by itself (starting in column 1). Currently, everything below each [new] is visually separated by having an alternate background color.

Alternate contributions (alternate [new]’s) are shaded, like this:

Someone’s contribution…

Someone else’s contribution.

Another contribution.

Yet another.

Putting [new::] will insert your UserName, and adds a timestamp to your contribution when you save the page. The timestamp appears when you move the mouse over the contribution. See also UsingPortraits.

<rant>

Please refrain from altering the above example’s wiki markup in an attempt to “clean it up”; usually this leaves it looking like this:

[new:SamuelBronson:2009-04-29 17:27 UTC]

<nowiki>, <code>, <pre>, {{...}}, etc. do not prevent it’s being expanded; you must actually prevent those characters from all appearing next to one another in the source of the page in order to prevent their being expanded. (This is arguably a bug.) Also, we must use <tt> to get fixed-width formatting because otherwised the <nowiki> tags used to break up the string show up:

[<nowiki>new::</nowiki>]

</rant>

A contribution after a [new] ends at either the next [new], the next heading (see below), or the next horizontal line (see above).

Use headings, horizontal lines or even new pages to separate threads of discussions, but use [new] to separate entries in the thread.

Source Code

Headings

Headings are enclosed in equals signs (=) on a line of their own. You can use up to six equals signs to produce headers of level one to six. Level one is the most important one, and should not be used because the page title already uses a level one heading. This is why level one headings are automatically translated to level two headings.

Example:

== Heading 2 ==
=== Heading 3 ===

Using two or three equals signs is recommended (== like this ==). Nothing beyond a level 4 heading is supported by the CSS stylesheet. After level 4, they are not displayed differently. Overuse of headings is poor style, as short Wiki pages are preferred to long ones. Consider splitting the page into two or more pages.

Images

To put an image on a page, insert the URL with an image suffix.

Example:

  http://www.emacswiki.org/emacs_logo.png

Result:

http://www.emacswiki.org/emacs_logo.png

Alternatively, put image: and a page name inside double square brackets to insert inline images. The images must exist on the Wiki, or be uploaded to a page on the Wiki. See UploadingImages.

Example:

  [[image:AngryFruitSaladTwo_Screenshot]]

Result:

AngryFruitSaladTwo_Screenshot

IRC Quotes

Discussions in the EmacsChannel can be copied directly to the Wiki.

Example:

<hybrid> emacs has a text adventure game in it
<PyroMithrandir> emacs IS a text adventure game

Result:

hybrid
emacs has a text adventure game in it
PyroMithrandir
emacs IS a text adventure game

Inclusion / Transclusion

A page on the wiki can “include” other pages. This is especially helpful for marking certain pages as out-of-date, requiring refactoring, candidates for deletion, or wiki projects.

<include "ExamplePage">

There is more to it, however. See Oddmuse:Transclusion.

The resulting HTML doesn’t tell you that ExamplePage has been transcluded, but if you’re on ExamplePage, clicking on the header will search for it. It’s up to the users to use a decent prefix to identify pages that are to be transcluded and to mention the page name this piece of text is from.

Rename / Redirect

To change the name of a page without losing all of the archived links to the original name, create a new page with the original content and new name, and redirect the old name, by replacing the entire page with: #REDIRECT FooBar”, where “FooBar” is the new, target Wiki page.

More details at PageRedirection

See Also

For questions, problems, and comments see TextFormattingDiscussion.

For discussions on formatting style see StyleGuide.

See also HowToEdit.


CategoryEmacsWikiSite