Changes between Version 3 and Version 4 of WikiFormatting


Ignore:
Timestamp:
Sep 10, 2014, 10:00:04 PM (7 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiFormatting

    v3 v4  
    88
    99
    10 This page demonstrates the formatting syntax available anywhere WikiFormatting is allowed.
    11 
    12 
    13 [[PageOutline(2,Markup Categories,inline)]]
     10This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed.
     11
     12The ''Cheat sheet'' below gives you a quick overview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page.
     13
     14A few other wiki pages present the advanced features of the Trac wiki markup in more depth:
     15 - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof,
     16 - WikiPageNames talks about the various names a wiki page can take, CamelCase or not
     17 - WikiMacros lists the macros available for generating dynamic content,
     18 - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways
     19
     20
     21== Cheat sheet ==
     22
     23||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =||
     24|-----------------------------------------------------------
     25{{{#!th rowspan=3
     26[#FontStyles Font Styles]
     27}}}
     28|| `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
     29|| '''bold''', ''italic'', '''''Wikipedia style''''' ||
     30|| {{{`monospaced (''other markup ignored'')`}}} || \
     31|| `monospaced (''other markup ignored'')` ||
     32|| `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
     33|| **bold**, //italic//, **//!WikiCreole style//** ||
     34|-----------------------------------------------------------
     35||= [#Headings Headings] =||\
     36{{{#!td
     37 {{{
     38 == Level 2 ==
     39 === Level 3 ^([#hn note])^
     40 }}}
     41}}}
     42{{{#!td style="padding-left: 2em"
     43== Level 2 ==
     44=== Level 3 ^([#hn note])^
     45}}}
     46|-----------------------------------------------------------
     47||= [#Paragraphs Paragraphs]  =||\
     48{{{#!td
     49 {{{
     50 First paragraph
     51 on multiple lines.
     52
     53 Second paragraph.
     54 }}}
     55}}}
     56{{{#!td
     57First paragraph
     58on multiple lines.
     59
     60Second paragraph.
     61}}}
     62|-----------------------------------------------------------
     63||= [#Lists Lists] =||\
     64{{{#!td
     65 {{{
     66 * bullets list
     67   on multiple lines
     68   1. nested list
     69     a. different numbering
     70        styles
     71 }}}
     72}}}
     73{{{#!td
     74* bullets list
     75  on multiple lines
     76  1. nested list
     77    a. different numbering
     78       styles
     79}}}
     80|-----------------------------------------------------------
     81{{{#!th
     82[#DefinitionLists Definition Lists]
     83}}}
     84{{{#!td
     85 {{{
     86  term:: definition on
     87         multiple lines
     88 }}}
     89}}}
     90{{{#!td
     91 term:: definition on
     92        multiple lines
     93}}}
     94|-----------------------------------------------------------
     95||= [#PreformattedText Preformatted Text] =||\
     96{{{#!td
     97 {{{
     98 {{{
     99 multiple lines, ''no wiki''
     100       white space respected
     101 }}}
     102 }}}
     103}}}
     104{{{#!td
     105 {{{
     106 multiple lines, ''no wiki''
     107       white space respected
     108 }}}
     109}}}
     110|-----------------------------------------------------------
     111||= [#Blockquotes Blockquotes] =||\
     112{{{#!td
     113 {{{
     114   if there's some leading
     115   space the text is quoted
     116 }}}
     117}}}
     118{{{#!td
     119 if there's some leading
     120 space the text is quoted
     121}}}
     122|-----------------------------------------------------------
     123||= [#DiscussionCitations Discussion Citations] =||\
     124{{{#!td
     125 {{{
     126 >> ... (I said)
     127 > (he replied)
     128 }}}
     129}}}
     130{{{#!td
     131>>... (I said)
     132> (he replied)
     133}}}
     134|-----------------------------------------------------------
     135||= [#Tables Tables] =||\
     136{{{#!td
     137 {{{
     138 ||= Table Header =|| Cell ||
     139 ||||  (details below)  ||
     140 }}}
     141}}}
     142{{{#!td
     143||= Table Header =|| Cell ||
     144||||  (details below)  ||
     145}}}
     146|-----------------------------------------------------------
     147{{{#!th rowspan=2
     148[#Links Links]
     149}}}
     150|| `http://trac.edgewall.org` ||\
     151|| http://trac.edgewall.org ||
     152|| `WikiFormatting (CamelCase)` ||\
     153|| WikiFormatting (CamelCase) ||
     154|-----------------------------------------------------------
     155{{{#!th rowspan=5
     156[#TracLinks TracLinks]
     157}}}
     158|| `wiki:WikiFormatting`, `wiki:"WikiFormatting"` ||\
     159|| wiki:WikiFormatting, wiki:"WikiFormatting" ||
     160|| `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
     161|| #1 (ticket), [1] (changeset), {1} (report) ||
     162|| `ticket:1, ticket:1#comment:1` ||\
     163|| ticket:1, ticket:1#comment:1 ||
     164|| `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
     165|| Ticket [ticket:1], [ticket:1 ticket one] ||
     166|| `Ticket [[ticket:1]]`, `[[ticket:1|ticket one]]` ||\
     167|| Ticket [[ticket:1]], [[ticket:1|ticket one]] ||
     168|-----------------------------------------------------------
     169{{{#!th rowspan=2
     170[#SettingAnchors Setting Anchors]
     171}}}
     172|| `[=#point1 (1)] First...` ||\
     173|| [=#point1 (1)] First... ||
     174|| `see [#point1 (1)]` ||\
     175|| see [#point1 (1)] ||
     176|-----------------------------------------------------------
     177{{{#!th rowspan=3
     178[#Escaping Escaping Markup]
     179}}}
     180|| `!'' doubled quotes` ||\
     181|| !'' doubled quotes ||
     182|| `!wiki:WikiFormatting`, `!WikiFormatting` ||\
     183|| !wiki:WikiFormatting, !WikiFormatting ||
     184|| {{{`}}}`{{{-}}}`{{{`}}}` triple curly brackets` ||\
     185|| `{{{-}}}` triple curly brackets ||
     186|-----------------------------------------------------------
     187||= [#Images Images] =|| `[[Image(`''link''`)]]` || [[Image(htdocs:../common/trac_logo_mini.png)]] ||
     188|-----------------------------------------------------------
     189{{{#!th rowspan=2
     190[#Macros Macros]
     191}}}
     192|| `[[MacroList(*)]]` ||  ''(short list of all available macros)''  ||
     193|| `[[Image?]]` ||  ''(help for the Image macro)''  ||
     194|-----------------------------------------------------------
     195||= [#Processors Processors] =||\
     196{{{#!td
     197 {{{
     198 {{{
     199 #!div style="font-size: 80%"
     200 Code highlighting:
     201   {{{#!python
     202   hello = lambda: "world"
     203   }}}
     204 }}}
     205 }}}
     206}}}
     207{{{#!td style="padding-left: 2em"
     208 {{{
     209 #!div style="font-size: 80%"
     210 Code highlighting:
     211   {{{#!python
     212   hello = lambda: "world"
     213   }}}
     214 }}}
     215}}}
     216|-----------------------------------------------------------
     217||= [#Comments Comments] =||\
     218{{{#!td
     219 {{{
     220 {{{#!comment
     221 Note to Editors: ...
     222 }}}
     223 }}}
     224}}}
     225{{{#!td style="padding-left: 2em"
     226 {{{#!comment
     227 Note to Editors: ...
     228 }}}
     229}}}
     230|-----------------------------------------------------------
     231||= [#Miscellaneous Miscellaneous] =||\
     232{{{#!td
     233 {{{
     234 Line [[br]] break
     235 Line \\ break
     236 ----
     237 }}}
     238}}}
     239{{{#!td style="padding-left: 2em"
     240Line [[br]] break
     241Line \\ break
     242----
     243}}}
    14244
    15245
     
    32262   * ^superscript^
    33263   * ,,subscript,,
     264   * **also bold**, //italic as well//,
     265     and **'' bold italic **'' //(since 0.12)//
    34266  }}}
    35267}}}
     
    47279 * ^superscript^
    48280 * ,,subscript,,
     281 * **also bold**, //italic as well//,
     282   and **'' bold italic **'' //(since 0.12)//
    49283}}}
    50284
     
    53287 * {{{ ! }}} tells wiki parser to not take the following characters as wiki format, so pay attention to put a space after !, e.g. when ending bold.
    54288 * all the font styles marks have to be used in opening/closing pairs,
    55    and they must nest properly
     289   and they must nest properly (in particular, an `''` italic can't be paired
     290   with a `//` one, and `'''` can't be paired with `**`)
     291
    56292
    57293== Headings ==
    58294
    59295You can create heading by starting a line with one up to six ''equal'' characters ("=")
    60 followed by a single space and the headline text. The headline text can be
    61 followed by the same number of ''='' characters, but this is no longer mandatory.
    62 The heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.
     296followed by a single space and the headline text.
     297
     298[=#hn]
     299The headline text can be followed by the same number of "=" characters, but this is no longer mandatory.
     300
     301Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.
    63302
    64303||= Wiki Markup =||= Display =||
     
    75314  {{{
    76315  #!div
     316  = Heading =
    77317  == Subheading
    78318  === About ''this'' ===
     
    361601}}}
    362602
    363 Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets.  If the descriptive title is omitted, then the explicit prefix is discarded, unless the link is an external link. This can be useful for wiki pages not adhering to the WikiPageNames convention.
    364 
    365 ||= Wiki Markup =||= Display =||
    366 {{{#!td
    367   {{{
    368    * [http://www.edgewall.com/ Edgewall Software]
    369    * [wiki:TitleIndex Title Index]
     603Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets.
     604If the descriptive title is omitted, then the explicit prefix is discarded, unless the link is an external link. This can be useful for wiki pages not adhering to the WikiPageNames convention.
     605
     606||= Wiki Markup =||= Display =||
     607{{{#!td
     608  {{{
     609   * [http://www.edgewall.com Edgewall Software]
     610   * [wiki:TitleIndex Title Index]
     611   * [wiki:TitleIndex]
    370612   * [wiki:ISO9000]
    371613  }}}
    372614}}}
    373615{{{#!td
    374  * [http://www.edgewall.com/ Edgewall Software]
    375  * [wiki:TitleIndex Title Index]
    376  * [wiki:ISO9000]
    377 }}}
     616   * [http://www.edgewall.com Edgewall Software]
     617   * [wiki:TitleIndex Title Index]
     618   * [wiki:TitleIndex]
     619   * [wiki:ISO9000]
     620}}}
     621
     622Following the [trac:WikiCreole] trend, the descriptive title can also be specified by writing the link followed by a pipe ('|') and a title and all this inside //double// square brackets.
     623
     624{{{#!td
     625  {{{
     626   * [[http://www.edgewall.com|Edgewall Software]]
     627   * [[wiki:TitleIndex|Title Index]]
     628     or even [[TitleIndex|Title Index]]
     629   * [[wiki:TitleIndex]]
     630     ''' but not ![[TitleIndex]]! '''
     631   * [[ISO9000]]
     632  }}}
     633}}}
     634{{{#!td
     635   * [[http://www.edgewall.com|Edgewall Software]]
     636   * [[wiki:TitleIndex|Title Index]]
     637     or even [[TitleIndex|Title Index]]
     638   * [[wiki:TitleIndex]]
     639     ''' but not ![[TitleIndex]]! '''
     640   * [[ISO9000]]
     641}}}
     642
     643'''Note''': the [trac:WikiCreole] style for links is quick to type and
     644certainly looks familiar as it's the one used on Wikipedia and in many
     645other wikis. Unfortunately it conflicts with the syntax for [#Macros macros].
     646So in the rare case when you need to refer to a page which is named after
     647a macro (typical examples being TitleIndex, InterTrac and InterWiki),
     648by writing `[[TitleIndex]]` you will actually call the macro instead of linking
     649to the page.
    378650
    379651== Trac Links ==
     
    388660   * Changesets: r1, [1] or changeset:1
    389661   * ...
     662   * targeting other Trac instances,
     663     so called InterTrac links:
     664     - Tickets: #Trac1 or Trac:ticket:1
     665     - Changesets: [Trac1] or Trac:changeset:1
    390666  }}}
    391667}}}
     
    395671 * Changesets: r1, [1] or changeset:1
    396672 * ...
    397 }}}
    398 
    399 There are many more flavors of Trac links, see TracLinks for more in-depth information.
    400 
    401 
    402 == Escaping Links and WikiPageNames ==
     673 * targeting other Trac instances,
     674   so called InterTrac links:
     675   - Tickets: #Trac1 or Trac:ticket:1
     676   - Changesets: [Trac1] or Trac:changeset:1
     677}}}
     678
     679There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers.
     680
     681
     682== Setting Anchors ==
     683
     684An anchor, or more correctly speaking, an [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, in order to uniquely identify a position in the document:
     685
     686{{{
     687[=#point1]
     688}}}
     689
     690This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]. For example:
     691{{{
     692== Long title == #title
     693}}}
     694
     695It's also very close to the syntax for the corresponding link to that anchor:
     696{{{
     697[#point1]
     698}}}
     699
     700Optionally, a label can be given to the anchor:
     701{{{
     702[[=#point1 '''Point 1''']]
     703}}}
     704
     705||= Wiki Markup =||= Display =||
     706|----------------------------------
     707{{{#!td
     708  {{{
     709  [#point2 jump to the second point]
     710
     711  ...
     712
     713  Point2:  [=#point2] Jump here
     714  }}}
     715}}}
     716{{{#!td
     717  [#point2 jump to the second point]
     718
     719  ...
     720
     721  Point2:  [=#point2] Jump here
     722}}}
     723
     724For more complex anchors (e.g. when a custom title is wanted), one can use the Span macro, e.g. `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.
     725
     726
     727== Escaping Links, WikiPageNames and other Markup == #Escaping
    403728
    404729You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).
     
    410735   !#42 is not a link
    411736  }}}
     737  {{{
     738Various forms of escaping for list markup:
     739 `-` escaped minus sign \\
     740 ``1. escaped number  \\
     741 {{{*}}} escaped asterisk sign
     742  }}}
    412743}}}
    413744{{{#!td
    414745 !NoHyperLink
    415746 !#42 is not a link
     747
     748Various forms of escaping for list markup:
     749 `-` escaped minus sign \\
     750 ``1. escaped number  \\
     751 {{{*}}} escaped asterisk sign
    416752}}}
    417753
     
    425761 * `[[Image(wiki:WikiFormatting:picture.gif)]]` (referring to attachment on another page)
    426762 * `[[Image(ticket:1:picture.gif)]]` (file attached to a ticket)
    427  * `[[Image(htdocs:picture.gif)]]` (referring to a file inside project htdocs)
     763 * `[[Image(htdocs:picture.gif)]]` (referring to a file inside the [TracEnvironment environment] `htdocs` directory)
    428764 * `[[Image(source:/trunk/trac/htdocs/trac_logo_mini.png)]]` (a file in repository)
    429765
     
    438774}}}
    439775
    440 See WikiMacros for further documentation on the `[[Image()]]` macro.
     776See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.)
    441777
    442778
     
    640976  {{{
    641977  Four or more dashes will be replaced
    642   by a horizontal line (<HR>)
     978  by an horizontal line (<HR>)
    643979  ----
    644980  See?
     
    647983{{{#!td
    648984Four or more dashes will be replaced
    649 by a horizontal line (<HR>)
     985by an horizontal line (<HR>)
    650986----
    651987See?
    652988}}}
    653 
    654 
    655 ----
    656 See also: TracLinks, TracGuide, WikiHtml, WikiMacros, WikiProcessors, TracSyntaxColoring.
     989|----------------------------------
     990{{{#!td
     991  {{{
     992  "macro" style [[br]] line break
     993  }}}
     994}}}
     995{{{#!td
     996"macro" style [[br]] line break
     997}}}
     998|----------------------------------
     999{{{#!td
     1000  {{{
     1001  !WikiCreole style \\ line\\break
     1002  }}}
     1003}}}
     1004{{{#!td
     1005!WikiCreole style \\ line\\break
     1006}}}
     1007