Changes between Version 4 and Version 5 of WikiFormatting


Ignore:
Timestamp:
Sep 14, 2021, 8:35:10 AM (3 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiFormatting

    v4 v5  
    33[[TracGuideToc]]
    44
    5 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole.
    6 
    7 Trac has a built-in small and powerful wiki rendering engine. This wiki engine implements a growing subset of the commands from other popular Wikis, especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole].
    8 
    9 This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed.
    10 
    11 The sections below provide an overview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page.
    12 
    13 A few other wiki pages present the advanced features of the Trac wiki markup in more depth:
    14  - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof.
     5Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and unified whole.
     6
     7Trac 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].
     8
     9The 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.
     10
     11The following wiki pages present the advanced features of the Trac wiki markup in more depth:
     12 - TracLinks covers all the possible ways to refer to any Trac resource or parts thereof.
    1513 - WikiPageNames covers the various names a wiki page can take, whether in CamelCase or not.
    1614 - WikiMacros lists the macros available for generating dynamic content.
    … …  
    2725|| `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
    2826|| '''bold''', ''italic'', '''''Wikipedia style''''' ||
     27|| `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
     28|| **bold**, //italic//, **//!WikiCreole style//** ||
    2929|| {{{`monospaced (''other markup ignored'')`}}} || \
    3030|| `monospaced (''other markup ignored'')` ||
    31 || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
    32 || **bold**, //italic//, **//!WikiCreole style//** ||
    3331|-----------------------------------------------------------
    3432||= [#Headings Headings] =||\
    35 {{{#!td 
     33{{{#!td
    3634 {{{
    3735 == Level 2
    … …  
    6664   on multiple lines
    6765   1. nested list
    68      a. different numbering 
     66     a. different numbering
    6967        styles
    7068 }}}
    … …  
    9694 {{{
    9795 {{{
    98  multiple lines, ''no wiki''
     96 multiple lines, ''no wiki'',
    9997       white space respected
    10098 }}}
    … …  
    103101{{{#!td
    104102 {{{
    105  multiple lines, ''no wiki''
     103 multiple lines, ''no wiki'',
    106104       white space respected
    107105 }}}
    … …  
    147145[#Links Links]
    148146}}}
    149 || `http://trac.edgewall.org` ||\
    150 || http://trac.edgewall.org ||
     147|| `https://trac.edgewall.org` ||\
     148|| https://trac.edgewall.org ||
    151149|| `WikiFormatting (CamelCase)` ||\
    152150|| WikiFormatting (CamelCase) ||
    … …  
    159157|| `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
    160158|| #1 (ticket), [1] (changeset), {1} (report) ||
    161 || `ticket:1, ticket:1#comment:1` ||\
    162 || ticket:1, ticket:1#comment:1 ||
     159|| `ticket:1, ticket:1#comment:1, comment:1:ticket:1` ||\
     160|| ticket:1, ticket:1#comment:1, comment:1:ticket:1 ||
    163161|| `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
    164162|| Ticket [ticket:1], [ticket:1 ticket one] ||
    … …  
    166164|| Ticket [[ticket:1]], [[ticket:1|ticket one]] ||
    167165|-----------------------------------------------------------
    168 {{{#!th rowspan=2 
     166{{{#!th rowspan=2
    169167[#SettingAnchors Setting Anchors]
    170168}}}
    … …  
    195193{{{#!td
    196194 {{{
    197  {{{
    198  #!div style="font-size: 80%"
     195 {{{#!div style="font-size: 80%"
    199196 Code highlighting:
    200197   {{{#!python
    … …  
    205202}}}
    206203{{{#!td style="padding-left: 2em"
    207  {{{
    208  #!div style="font-size: 80%"
     204 {{{#!div style="font-size: 80%"
    209205 Code highlighting:
    210    {{{#!python 
     206   {{{#!python
    211207   hello = lambda: "world"
    212208   }}}
    … …  
    222218 }}}
    223219}}}
    224 {{{#!td style="padding-left: 2em"
    225  {{{#!comment
    226  Note to Editors: ...
    227  }}}
    228 }}}
     220||  ''(comment is shown in edit mode only)''  ||
    229221|-----------------------------------------------------------
    230222||= [#Miscellaneous Miscellaneous] =||\
    231223{{{#!td
    232224 {{{
    233  Line [[br]] break 
     225 Line [[br]] break
    234226 Line \\ break
    235227 ----
    … …  
    248240{{{#!td
    249241  {{{
    250    * '''bold''', 
    251      ''' triple quotes !''' 
    252      can be bold too if prefixed by ! ''', 
     242   * '''bold''',
     243     ''' triple quotes !'''
     244     can be bold too if prefixed by ! ''',
    253245   * ''italic''
    254246   * '''''bold italic''''' or ''italic and
    … …  
    258250     (hence `{{{` or {{{`}}} quoting)
    259251   * ~~strike-through~~
    260    * ^superscript^ 
     252   * ^superscript^
    261253   * ,,subscript,,
    262    * **also bold**, //italic as well//, 
     254   * **also bold**, //italic as well//,
    263255     and **'' bold italic **'' //(since 0.12)//
    264256   * [[span(style=color: #FF0000, a red text )]]
    … …  
    266258}}}
    267259{{{#!td
    268  * '''bold''', 
    269    ''' triple quotes !''' 
    270    can be bold too if prefixed by ! ''', 
     260 * '''bold''',
     261   ''' triple quotes !'''
     262   can be bold too if prefixed by ! ''',
    271263 * ''italic''
    272264 * '''''bold italic''''' or ''italic and
    … …  
    276268   (hence `{{{` or {{{`}}} quoting)
    277269 * ~~strike-through~~
    278  * ^superscript^ 
     270 * ^superscript^
    279271 * ,,subscript,,
    280  * **also bold**, //italic as well//, 
     272 * **also bold**, //italic as well//,
    281273   and **'' bold italic **'' //(since 0.12)//
    282274 * [[span(style=color: #FF0000, a red text )]]
    … …  
    285277Notes:
    286278 * `{{{...}}}` 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.
    287  * {{{ ! }}} 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.
    288  * all the font styles marks have to be used in opening/closing pairs, 
    289    and they must nest properly; in particular, an `''` italic can't be paired 
     279 * {{{ ! }}} 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 * all the font styles marks have to be used in opening/closing pairs,
     281   and they must nest properly; in particular, an `''` italic can't be paired
    290282   with a `//` one, and `'''` can't be paired with `**`.
    291283
    292284== Headings
    293285
    294 You can create heading by starting a line with one up to six ''equal'' characters ("=") followed by a single space and the headline text.
     286You can create a heading by starting a line with one up to six ''equal'' characters (`=`) followed by a single space and the headline text.
    295287
    296288[=#hn]
    297 The headline text can be followed by the same number of "=" characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`.
     289The headline text can be followed by the same number of `=` characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`.
    298290
    299291Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.
    … …  
    334326  one
    335327
    336   Paragraph 
     328  Paragraph
    337329  two
    338330  }}}
    … …  
    341333  Line 1[[BR]]Line 2
    342334
    343   Paragraph 
     335  Paragraph
    344336  one
    345337
    346   Paragraph 
     338  Paragraph
    347339  two
    348340}}}
    … …  
    352344The wiki supports both ordered/numbered and unordered lists.
    353345
    354 Example:
    355346||= Wiki Markup =||= Display =||
    356347{{{#!td
    … …  
    358349   * Item 1
    359350     * Item 1.1
    360         * Item 1.1.1   
     351        * Item 1.1.1
    361352        * Item 1.1.2
    362353        * Item 1.1.3
    … …  
    365356  - items can start at the beginning of a line
    366357    and they can span multiple lines
    367     - be careful though to continue the line 
     358    - be careful though to continue the line
    368359    with the appropriate indentation, otherwise
    369360  that will start a new paragraph...
    370  
     361
    371362   1. Item 1
    372363     a. Item 1.a
    … …  
    383374 * Item 1
    384375   * Item 1.1
    385       * Item 1.1.1   
     376      * Item 1.1.1
    386377      * Item 1.1.2
    387378      * Item 1.1.3
    … …  
    390381- items can start at the beginning of a line
    391382  and they can span multiple lines
    392   - be careful though to continue the line 
     383  - be careful though to continue the line
    393384  with the appropriate indentation, otherwise
    394385that will start a new paragraph...
    … …  
    431422
    432423Block 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.
    433  
     424
    434425||= Wiki Markup =||= Display =||
    435426{{{#!td
    … …  
    468459== Discussion Citations
    469460
    470 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (">", ">>", etc.) may be used. 
     461To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (`>`, `>>`, etc.) may be used.
    471462
    472463||= Wiki Markup =||= Display =||
    … …  
    489480=== Simple Tables
    490481
    491 Simple tables can be created like this:
     482Simple tables can be created:
    492483||= Wiki Markup =||= Display =||
    493484{{{#!td
    … …  
    502493}}}
    503494
    504 Cell headings can be specified by wrapping the content in a pair of '=' characters.
    505 Note that the '=' characters have to stick to the cell separators, like this:
     495Cell headings can be specified by wrapping the content in a pair of `=` characters.
     496Note that the `=` characters have to stick to the cell separators:
    506497||= Wiki Markup =||= Display =||
    507498{{{#!td
    … …  
    518509}}}
    519510
    520 Finally, specifying an empty cell means that the next non empty cell will span the empty cells. For example:
     511Finally, specifying an empty cell means that the next non empty cell will span the empty cells:
    521512||= Wiki Markup =||= Display =||
    522513{{{#!td
    … …  
    535526}}}
    536527
    537 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:
     528Note 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:
    538529||= Wiki Markup =||= Display =||
    539530{{{#!td
    … …  
    560551}}}
    561552
    562 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.
     553If 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:
    563554
    564555||= Wiki Markup =||
    565556{{{#!td
    566557  {{{
    567   || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
    568   || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
     558  || this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
     559  || this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
    569560  || that's column 3 and last one ||
    570561  }}}
    … …  
    573564||= Display =||
    574565{{{#!td style="padding: 2em;"
    575 || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
    576 || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
     566|| this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
     567|| this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
    577568|| that's column 3 and last one ||
    578569}}}
    … …  
    580571=== Complex Tables
    581572
    582 If 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].
     573If 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].
    583574
    584575== Links
    585576
    586 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark ('!'), such as {{{!WikiPageLink}}}.
    587 
    588 ||= Wiki Markup =||= Display =||
    589 {{{#!td
    590   {{{
    591   TitleIndex, http://www.edgewall.com/, !NotAlink
    592   }}}
    593 }}}
    594 {{{#!td
    595 TitleIndex, http://www.edgewall.com/, !NotAlink
    596 }}}
    597 
    598 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. 
     577Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark (`!`), such as `!WikiPageLink`.
     578
     579||= Wiki Markup =||= Display =||
     580{{{#!td
     581  {{{
     582  TitleIndex, https://www.edgewall.com/, !NotAlink
     583  }}}
     584}}}
     585{{{#!td
     586TitleIndex, https://www.edgewall.com/, !NotAlink
     587}}}
     588
     589Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets.
    599590If 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.
    600591
    … …  
    602593{{{#!td
    603594  {{{
    604    * [http://www.edgewall.com Edgewall Software]
    605    * [wiki:TitleIndex Title Index] 
    606    * [wiki:TitleIndex] 
     595   * [https://www.edgewall.com Edgewall Software]
     596   * [wiki:TitleIndex Title Index]
     597   * [wiki:TitleIndex]
    607598   * [wiki:ISO9000]
    608599  }}}
    609600}}}
    610601{{{#!td
    611    * [http://www.edgewall.com Edgewall Software]
    612    * [wiki:TitleIndex Title Index] 
    613    * [wiki:TitleIndex] 
     602   * [https://www.edgewall.com Edgewall Software]
     603   * [wiki:TitleIndex Title Index]
     604   * [wiki:TitleIndex]
    614605   * [wiki:ISO9000]
    615606}}}
    616607
    617 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.
    618 
    619 {{{#!td
    620   {{{
    621    * [[http://www.edgewall.com|Edgewall Software]]
     608Following 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.
     609
     610{{{#!td
     611  {{{
     612   * [[https://www.edgewall.com|Edgewall Software]]
    622613   * [[wiki:TitleIndex|Title Index]]
    623614     or even [[TitleIndex|Title Index]]
    … …  
    628619}}}
    629620{{{#!td
    630    * [[http://www.edgewall.com|Edgewall Software]]
     621   * [[https://www.edgewall.com|Edgewall Software]]
    631622   * [[wiki:TitleIndex|Title Index]]
    632623     or even [[TitleIndex|Title Index]]
    … …  
    650641   * Changesets: r1, [1] or changeset:1
    651642   * ...
    652    * targeting other Trac instances, 
     643   * targeting other Trac instances,
    653644     so called InterTrac links:
    654645     - Tickets: #Trac1 or Trac:ticket:1
    … …  
    660651 * Reports: {1} or report:1
    661652 * Changesets: r1, [1] or changeset:1
    662  * ... 
    663  * targeting other Trac instances, 
     653 * ...
     654 * targeting other Trac instances,
    664655   so called InterTrac links:
    665656   - Tickets: #Trac1 or Trac:ticket:1
    … …  
    671662== Setting Anchors
    672663
    673 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:
     664An 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:
    674665
    675666{{{
    … …  
    677668}}}
    678669
    679 This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]. For example:
     670This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]:
    680671{{{
    681672== Long title == #title
    … …  
    689680Optionally, a label can be given to the anchor:
    690681{{{
    691 [[=#point1 '''Point 1''']]
     682[=#point1 '''Point 1''']
    692683}}}
    693684
    … …  
    715706== Escaping Links, WikiPageNames and other Markup == #Escaping
    716707
    717 You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark ('!').
     708You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark (`!`).
    718709
    719710||= Wiki Markup =||= Display =||
    … …  
    766757== Macros
    767758
    768 Macros are ''custom functions'' to insert dynamic content in a page.
     759Macros are ''custom functions'' that insert dynamic content in a page.
    769760
    770761||= Wiki Markup =||= Display =||
    … …  
    780771See WikiMacros for more information, and a list of installed macros.
    781772
    782 The detailed help for a specific macro can also be obtained more directly by appending a "?" to the macro name.
     773The detailed help for a specific macro can also be obtained more directly by appending a `?` to the macro name.
    783774
    784775||= Wiki Markup =||= Display =||
    … …  
    794785== Processors
    795786
    796 Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in 
    797 [wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML]. 
     787Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in
     788[wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML].
    798789
    799790||= Wiki Markup =||= Display =||
    … …  
    807798{{{#!td style="border: 0px"
    808799  {{{
    809   {{{
    810   #!html
     800  {{{#!html
    811801  <h1 style="text-align: right; color: blue">
    812802   HTML Test
    … …  
    817807{{{#!td valign="top"  style="border: 0px"
    818808
    819 {{{
    820 #!html
     809{{{#!html
    821810<h1 style="text-align: right; color: blue">HTML Test</h1>
    822811}}}
    … …  
    832821{{{#!td style="border: 0px"
    833822  {{{
    834   {{{
    835   #!python
     823  {{{#!python
    836824  class Test:
    837  
     825
    838826      def __init__(self):
    839827          print "Hello World"
    … …  
    843831  }}}
    844832}}}
    845 {{{
    846 #!td valign="top"  style="border: 0px"
    847 
    848 {{{
    849 #!python
     833{{{#!td valign="top"  style="border: 0px"
     834
     835{{{#!python
    850836class Test:
    851837    def __init__(self):
    … …  
    877863  |----------------
    878864  {{{#!td
    879   As processors can be easily nested, 
     865  As processors can be easily nested,
    880866  so can be tables:
    881867    {{{#!th
    … …  
    894880  }}}
    895881}}}
    896 {{{
    897 #!td  valign="top"  style="border: 0px"
     882{{{#!td  valign="top"  style="border: 0px"
    898883
    899884  {{{#!th rowspan=4 align=justify
    … …  
    909894  |----------------
    910895  {{{#!td
    911   As processors can be easily nested, 
     896  As processors can be easily nested,
    912897  so can be tables:
    913898    {{{#!th
    … …  
    937922  {{{
    938923  Nothing to
    939   {{{
    940   #!comment
     924  {{{#!comment
    941925  Your comment for editors here
    942926  }}}
    … …  
    946930{{{#!td
    947931  Nothing to
    948   {{{
    949   #!comment
     932  {{{#!comment
    950933  Your comment for editors here
    951934  }}}
    … …  
    959942  Horizontal line:
    960943  {{{
    961   Four or more dashes will be replaced 
     944  Four or more dashes will be replaced
    962945  by a horizontal line (<HR>)
    963946  ----