Edgewall Software

Changes between Version 109 and Version 127 of WikiFormatting


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified
  • WikiFormatting

    v109 v127  
    1 ** Note: this page documents the 0.12 version of Trac, see [[0.11/WikiFormatting]] if you need the previous version **
    2 
    3 = WikiFormatting =
     1= WikiFormatting
     2
    43[[TracGuideToc]]
    54[[TranslatedPages]]
    65
    7 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole.
    8 
    9 Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis,
    10 especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole].
    11 
    12 
    13 This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed.
    14 
    15 The ''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.
    16 
    17 A few other wiki pages present the advanced features of the Trac wiki markup in more depth:
    18  - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof,
    19  - WikiPageNames talks about the various names a wiki page can take, CamelCase or not
    20  - WikiMacros lists the macros available for generating dynamic content,
    21  - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways
    22 
    23 
    24 == Cheat sheet ==
     6Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and unified whole.
     7
     8Trac has a powerful wiki rendering engine that implements a subset of the commands from other popular Wikis, such as [https://moinmo.in/ MoinMoin] and [trac:WikiCreole].
     9
     10The sections below provide an overview for the most common syntax, each link in the ''Category'' column leads you to the more detailed explanation later in this page.
     11
     12The following wiki pages present the advanced features of the Trac wiki markup in more depth:
     13 - TracLinks covers all the possible ways to refer to any Trac resource or parts thereof.
     14 - WikiPageNames covers the various names a wiki page can take, whether in CamelCase or not.
     15 - WikiMacros lists the macros available for generating dynamic content.
     16 - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways.
     17 - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios.
     18
     19== Common wiki markup
    2520
    2621||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =||
     
    3126|| `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
    3227|| '''bold''', ''italic'', '''''Wikipedia style''''' ||
    33 || {{{`monospaced and ''nowiki''`}}} || \
    34 || `monospaced and ''nowiki''` ||
    3528|| `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
    3629|| **bold**, //italic//, **//!WikiCreole style//** ||
     30|| {{{`monospaced (''other markup ignored'')`}}} || \
     31|| `monospaced (''other markup ignored'')` ||
    3732|-----------------------------------------------------------
    3833||= [#Headings Headings] =||\
    3934{{{#!td
    4035 {{{
    41  == Level 2 ==
     36 == Level 2
    4237 === Level 3 ^([#hn note])^
    4338 }}}
    4439}}}
    4540{{{#!td style="padding-left: 2em"
    46 == Level 2 ==
     41== Level 2
    4742=== Level 3 ^([#hn note])^
    4843}}}
     
    6762{{{#!td
    6863 {{{
    69  * bullets list
     64 * bullet list
    7065   on multiple lines
    7166   1. nested list
     
    7570}}}
    7671{{{#!td
    77 * bullets list
     72* bullet list
    7873  on multiple lines
    7974  1. nested list
     
    10095 {{{
    10196 {{{
    102  multiple lines, ''no wiki''
     97 multiple lines, ''no wiki'',
    10398       white space respected
    10499 }}}
     
    107102{{{#!td
    108103 {{{
    109  multiple lines, ''no wiki''
     104 multiple lines, ''no wiki'',
    110105       white space respected
    111106 }}}
     
    151146[#Links Links]
    152147}}}
    153 || `http://trac.edgewall.org` ||\
    154 || http://trac.edgewall.org ||
     148|| `https://trac.edgewall.org` ||\
     149|| https://trac.edgewall.org ||
    155150|| `WikiFormatting (CamelCase)` ||\
    156151|| WikiFormatting (CamelCase) ||
     
    163158|| `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
    164159|| #1 (ticket), [1] (changeset), {1} (report) ||
    165 || `ticket:1, ticket:1#comment:1` ||\
    166 || ticket:1, ticket:1#comment:1 ||
     160|| `ticket:1, ticket:1#comment:1, comment:1:ticket:1` ||\
     161|| ticket:1, ticket:1#comment:1, comment:1:ticket:1 ||
    167162|| `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
    168163|| Ticket [ticket:1], [ticket:1 ticket one] ||
     
    179174|-----------------------------------------------------------
    180175{{{#!th rowspan=3
    181 [#EscapingLinksandWikiPageNames Escaping Markup]
     176[#Escaping Escaping Markup]
    182177}}}
    183178|| `!'' doubled quotes` ||\
     
    185180|| `!wiki:WikiFormatting`, `!WikiFormatting` ||\
    186181|| !wiki:WikiFormatting, !WikiFormatting ||
    187 || `{{{-}}} curly brackets` ||\
    188 || {{{-}}} curly brackets ||
     182|| [[html(<code>`{{{-}}}` triple curly brackets</code>)]] ||\
     183|| `{{{-}}}` triple curly brackets ||
    189184|-----------------------------------------------------------
    190185||= [#Images Images] =|| `[[Image(`''link''`)]]` || [[Image(htdocs:../common/trac_logo_mini.png)]] ||
     
    199194{{{#!td
    200195 {{{
    201  {{{
    202  #!div style="font-size: 80%"
     196 {{{#!div style="font-size: 80%"
    203197 Code highlighting:
    204198   {{{#!python
     
    209203}}}
    210204{{{#!td style="padding-left: 2em"
    211  {{{
    212  #!div style="font-size: 80%"
     205 {{{#!div style="font-size: 80%"
    213206 Code highlighting:
    214207   {{{#!python
     
    226219 }}}
    227220}}}
    228 {{{#!td style="padding-left: 2em"
    229  {{{#!comment
    230  Note to Editors: ...
    231  }}}
    232 }}}
     221||  ''(comment is shown in edit mode only)''  ||
    233222|-----------------------------------------------------------
    234223||= [#Miscellaneous Miscellaneous] =||\
     
    246235}}}
    247236
    248 
    249 == Font Styles ==
     237== Font Styles
    250238
    251239The Trac wiki supports the following font styles:
     
    267255   * **also bold**, //italic as well//,
    268256     and **'' bold italic **'' //(since 0.12)//
     257   * [[span(style=color: #FF0000, a red text )]]
    269258  }}}
    270259}}}
     
    284273 * **also bold**, //italic as well//,
    285274   and **'' bold italic **'' //(since 0.12)//
     275 * [[span(style=color: #FF0000, a red text )]]
    286276}}}
    287277
    288278Notes:
    289279 * `{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but also treat their content as verbatim text, meaning that no further wiki processing is done on this text.
    290  * {{{ ! }}} 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.
     280 * {{{ ! }}} 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.
    291281 * all the font styles marks have to be used in opening/closing pairs,
    292    and they must nest properly (in particular, an `''` italic can't be paired
    293    with a `//` one, and `'''` can't be paired with `**`)
    294 
    295 
    296 == Headings ==
    297 
    298 You can create heading by starting a line with one up to six ''equal'' characters ("=")
    299 followed by a single space and the headline text.
     282   and they must nest properly; in particular, an `''` italic can't be paired
     283   with a `//` one, and `'''` can't be paired with `**`.
     284
     285== Headings
     286
     287You can create a heading by starting a line with one up to six ''equal'' characters (`=`) followed by a single space and the headline text.
    300288
    301289[=#hn]
    302 The headline text can be followed by the same number of "=" characters, but this is no longer mandatory.
     290The headline text can be followed by the same number of `=` characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`.
    303291
    304292Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.
     
    325313}}}
    326314
    327 == Paragraphs ==
     315== Paragraphs
    328316
    329317A new text paragraph is created whenever two blocks of text are separated by one or more empty lines.
     
    353341}}}
    354342
    355 == Lists ==
     343== Lists
    356344
    357345The wiki supports both ordered/numbered and unordered lists.
    358346
    359 Example:
    360347||= Wiki Markup =||= Display =||
    361348{{{#!td
     
    409396}}}
    410397
    411 
    412 == Definition Lists ==
     398== Definition Lists
    413399
    414400The wiki also supports definition lists.
     
    434420Note that you need a space in front of the defined term.
    435421
    436 
    437 == Preformatted Text ==
     422== Preformatted Text
    438423
    439424Block containing preformatted text are suitable for source code snippets, notes and examples. Use three ''curly braces'' wrapped around the text to define a block quote. The curly braces need to be on a separate line.
     
    457442Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors.
    458443
    459 == Blockquotes ==
     444== Blockquotes
    460445
    461446In order to mark a paragraph as blockquote, indent that paragraph with two spaces.
     
    473458}}}
    474459
    475 == Discussion Citations ==
    476 
    477 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, e-mail-like citation marks (">", ">>", etc.) may be used. 
     460== Discussion Citations
     461
     462To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (`>`, `>>`, etc.) may be used. 
    478463
    479464||= Wiki Markup =||= Display =||
     
    493478}}}
    494479
    495 
    496 == Tables ==
    497 === Simple Tables ===
    498 Simple tables can be created like this:
     480== Tables
     481=== Simple Tables
     482
     483Simple tables can be created:
    499484||= Wiki Markup =||= Display =||
    500485{{{#!td
     
    509494}}}
    510495
    511 Cell headings can be specified by wrapping the content in a pair of '=' characters.
    512 Note that the '=' characters have to stick to the cell separators, like this:
     496Cell headings can be specified by wrapping the content in a pair of `=` characters.
     497Note that the `=` characters have to stick to the cell separators:
    513498||= Wiki Markup =||= Display =||
    514499{{{#!td
     
    525510}}}
    526511
    527 Finally, specifying an empty cell means that the next non empty cell will span the empty cells. For example:
     512Finally, specifying an empty cell means that the next non empty cell will span the empty cells:
    528513||= Wiki Markup =||= Display =||
    529514{{{#!td
     
    542527}}}
    543528
    544 Note that if the content of a cell "sticks" to one side of the cell and only one, then the text will be aligned on that side. Example:
     529Note that if the content of a cell sticks to one side of the cell and only one, then the text will be aligned on that side:
    545530||= Wiki Markup =||= Display =||
    546531{{{#!td
     
    567552}}}
    568553
    569 If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line.
     554If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line:
    570555
    571556||= Wiki Markup =||
    572557{{{#!td
    573558  {{{
    574   || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
    575   || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
     559  || this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
     560  || this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
    576561  || that's column 3 and last one ||
    577562  }}}
     
    580565||= Display =||
    581566{{{#!td style="padding: 2em;"
    582 || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
    583 || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
     567|| this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
     568|| this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
    584569|| that's column 3 and last one ||
    585570}}}
    586571
    587 === Complex Tables ===
    588 
    589 If the possibilities offered by the simple "pipe"-based markup for tables described above are not enough for your needs, you can create more elaborated tables by using [#Processors-example-tables WikiProcessor based tables].
    590 
    591 
    592 == Links ==
    593 
    594 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}.
    595 
    596 ||= Wiki Markup =||= Display =||
    597 {{{#!td
    598   {{{
    599   TitleIndex, http://www.edgewall.com/, !NotAlink
    600   }}}
    601 }}}
    602 {{{#!td
    603 TitleIndex, http://www.edgewall.com/, !NotAlink
     572=== Complex Tables
     573
     574If the possibilities offered by the simple pipe-based markup (`||`) for tables described above are not enough for your needs, you can create more elaborate tables by using [#Processors-example-tables WikiProcessor based tables].
     575
     576== Links
     577
     578Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark (`!`), such as `!WikiPageLink`.
     579
     580||= Wiki Markup =||= Display =||
     581{{{#!td
     582  {{{
     583  TitleIndex, https://www.edgewall.com/, !NotAlink
     584  }}}
     585}}}
     586{{{#!td
     587TitleIndex, https://www.edgewall.com/, !NotAlink
    604588}}}
    605589
     
    610594{{{#!td
    611595  {{{
    612    * [http://www.edgewall.com Edgewall Software]
     596   * [https://www.edgewall.com Edgewall Software]
    613597   * [wiki:TitleIndex Title Index]
    614598   * [wiki:TitleIndex]
     
    617601}}}
    618602{{{#!td
    619    * [http://www.edgewall.com Edgewall Software]
     603   * [https://www.edgewall.com Edgewall Software]
    620604   * [wiki:TitleIndex Title Index]
    621605   * [wiki:TitleIndex]
     
    623607}}}
    624608
    625 Following 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.
    626 
    627 {{{#!td
    628   {{{
    629    * [[http://www.edgewall.com|Edgewall Software]]
     609Following 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.
     610
     611{{{#!td
     612  {{{
     613   * [[https://www.edgewall.com|Edgewall Software]]
    630614   * [[wiki:TitleIndex|Title Index]]
    631615     or even [[TitleIndex|Title Index]]
     
    636620}}}
    637621{{{#!td
    638    * [[http://www.edgewall.com|Edgewall Software]]
     622   * [[https://www.edgewall.com|Edgewall Software]]
    639623   * [[wiki:TitleIndex|Title Index]]
    640624     or even [[TitleIndex|Title Index]]
     
    644628}}}
    645629
    646 '''Note''': the [trac:WikiCreole] style for links is quick to type and
    647 certainly looks familiar as it's the one used on Wikipedia and in many
    648 other wikis. Unfortunately it conflicts with the syntax for [#Macros macros].
    649 So in the rare case when you need to refer to a page which is named after
    650 a macro (typical examples being TitleIndex, InterTrac and InterWiki),
    651 by writing `[[TitleIndex]]` you will actually call the macro instead of linking
    652 to the page.
    653 
    654 == Trac Links ==
     630'''Note''': the [trac:WikiCreole] style for links is quick to type and certainly looks familiar as it is the one used on Wikipedia and in many other wikis. Unfortunately it conflicts with the syntax for [#Macros macros].
     631So in the rare case when you need to refer to a page which is named after a macro (typical examples being TitleIndex, InterTrac and InterWiki), by writing `[[TitleIndex]]` you will actually call the macro instead of linking to the page.
     632
     633== Trac Links
    655634
    656635Wiki pages can link directly to other parts of the Trac system. Pages can refer to tickets, reports, changesets, milestones, source files and other Wiki pages using the following notations:
     
    682661There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers.
    683662
    684 
    685 == Setting Anchors ==
    686 
    687 An 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:
     663== Setting Anchors
     664
     665An anchor, or more correctly speaking, an [https://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, to uniquely identify a position in the document:
    688666
    689667{{{
     
    691669}}}
    692670
    693 This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]. For example:
     671This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]:
    694672{{{
    695673== Long title == #title
    696674}}}
    697675
    698 It's also very close to the syntax for the corresponding link to that anchor:
     676It is also very close to the syntax for the corresponding link to that anchor:
    699677{{{
    700678[#point1]
     
    703681Optionally, a label can be given to the anchor:
    704682{{{
    705 [[=#point1 '''Point 1''']]
     683[=#point1 '''Point 1''']
    706684}}}
    707685
     
    725703}}}
    726704
    727 For 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)^)]]`.
    728 
    729 
    730 == Escaping Links and WikiPageNames ==
    731 
    732 You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).
     705For more complex anchors (eg when a custom title is wanted), you can use the Span macro: `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.
     706
     707== Escaping Links, WikiPageNames and other Markup == #Escaping
     708
     709You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark (`!`).
    733710
    734711||= Wiki Markup =||= Display =||
     
    739716  }}}
    740717  {{{
    741    {{{-}}} minus sign at the beginning of a line doesn't start a list \\
    742    {{{1.}}} number at the beginning of a line doesn't start a list \\
    743    {{{*}}} asterisk sign at the beginning of a line doesn't start a list
     718Various forms of escaping for list markup:
     719 ^^- escaped minus sign \\
     720 ^^1. escaped number  \\
     721 ^^* escaped asterisk sign
    744722  }}}
    745723}}}
     
    747725 !NoHyperLink
    748726 !#42 is not a link
    749 |-----------------------------------------------------------
    750  {{{-}}} minus sign at the beginning of a line doesn't start a list \\
    751  {{{1.}}} number at the beginning of a line doesn't start a list \\
    752  {{{*}}} asterisk sign at the beginning of a line doesn't start a list
    753 }}}
    754 
    755 == Images ==
     727
     728Various forms of escaping for list markup:
     729 ^^- escaped minus sign \\
     730 ^^1. escaped number  \\
     731 ^^* escaped asterisk sign
     732}}}
     733
     734== Images
    756735
    757736Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags.
     
    777756See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.)
    778757
    779 
    780 == Macros ==
    781 
    782 Macros are ''custom functions'' to insert dynamic content in a page.
     758== Macros
     759
     760Macros are ''custom functions'' that insert dynamic content in a page.
    783761
    784762||= Wiki Markup =||= Display =||
     
    794772See WikiMacros for more information, and a list of installed macros.
    795773
    796 The detailed help for a specific macro can also be obtained more directly by appending a "?" to the macro name.
     774The detailed help for a specific macro can also be obtained more directly by appending a `?` to the macro name.
    797775
    798776||= Wiki Markup =||= Display =||
     
    806784}}}
    807785
    808 
    809 == Processors ==
     786== Processors
    810787
    811788Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in
     
    822799{{{#!td style="border: 0px"
    823800  {{{
    824   {{{
    825   #!html
     801  {{{#!html
    826802  <h1 style="text-align: right; color: blue">
    827803   HTML Test
     
    832808{{{#!td valign="top"  style="border: 0px"
    833809
    834 {{{
    835 #!html
     810{{{#!html
    836811<h1 style="text-align: right; color: blue">HTML Test</h1>
    837812}}}
     
    847822{{{#!td style="border: 0px"
    848823  {{{
    849   {{{
    850   #!python
     824  {{{#!python
    851825  class Test:
    852826 
     
    858832  }}}
    859833}}}
    860 {{{
    861 #!td valign="top"  style="border: 0px"
    862 
    863 {{{
    864 #!python
     834{{{#!td valign="top"  style="border: 0px"
     835
     836{{{#!python
    865837class Test:
    866838    def __init__(self):
     
    909881  }}}
    910882}}}
    911 {{{
    912 #!td  valign="top"  style="border: 0px"
     883{{{#!td  valign="top"  style="border: 0px"
    913884
    914885  {{{#!th rowspan=4 align=justify
     
    944915See WikiProcessors for more information.
    945916
    946 
    947 == Comments ==
     917== Comments
    948918
    949919Comments can be added to the plain text. These will not be rendered and will not display in any other format than plain text.
     
    953923  {{{
    954924  Nothing to
    955   {{{
    956   #!comment
     925  {{{#!comment
    957926  Your comment for editors here
    958927  }}}
    959   see ;-)
     928  see.
    960929  }}}
    961930}}}
    962931{{{#!td
    963932  Nothing to
    964   {{{
    965   #!comment
     933  {{{#!comment
    966934  Your comment for editors here
    967935  }}}
    968   see ;-)
    969 }}}
    970 
    971 == Miscellaneous ==
    972 
    973 An horizontal line can be used to separated different parts of your page:
    974 
    975 ||= Wiki Markup =||= Display =||
    976 {{{#!td
     936  see.
     937}}}
     938
     939== Miscellaneous
     940
     941||= Wiki Markup =||= Display =||
     942{{{#!td
     943  Horizontal line:
    977944  {{{
    978945  Four or more dashes will be replaced
    979   by an horizontal line (<HR>)
     946  by a horizontal line (<HR>)
    980947  ----
    981948  See?
     
    984951{{{#!td
    985952Four or more dashes will be replaced
    986 by an horizontal line (<HR>)
     953by a horizontal line (<HR>)
    987954----
    988955See?
     
    990957|----------------------------------
    991958{{{#!td
    992   {{{
    993   "macro" style [[br]] line break
    994   }}}
    995 }}}
    996 {{{#!td
    997 "macro" style [[br]] line break
     959  Two examples of line breaks:
     960  {{{
     961  "macro" style [[BR]] line break
     962  }}}
     963  or:
     964  {{{
     965  !WikiCreole style \\ line\\break
     966  }}}
     967}}}
     968{{{#!td
     969"macro" style [[BR]] line break
     970
     971!WikiCreole style \\ line\\break
    998972}}}
    999973|----------------------------------
    1000 {{{#!td
    1001   {{{
    1002   !WikiCreole style \\ line\\break
    1003   }}}
    1004 }}}
    1005 {{{#!td
    1006 !WikiCreole style \\ line\\break
    1007 }}}
    1008