Changes between Version 5 and Version 6 of WikiFormatting
- Timestamp:
- Feb 4, 2019, 3:13:39 PM (6 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WikiFormatting
v5 v6 1 = WikiFormatting = 1 = WikiFormatting 2 2 3 [[TracGuideToc]] 3 4 4 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole. 5 6 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, 7 especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole]. 8 9 10 This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed. 11 12 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. 13 14 A 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 == 5 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and unified whole. 6 7 Trac has a powerful wiki rendering engine that implements a subset of the commands from other popular Wikis, such as [http://moinmo.in/ MoinMoin] and [trac:WikiCreole]. 8 9 The 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 11 The 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. 13 - WikiPageNames covers the various names a wiki page can take, whether in CamelCase or not. 14 - WikiMacros lists the macros available for generating dynamic content. 15 - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways. 16 - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios. 17 18 == Common wiki markup 22 19 23 20 ||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =|| … … 28 25 || `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \ 29 26 || '''bold''', ''italic'', '''''Wikipedia style''''' || 27 || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \ 28 || **bold**, //italic//, **//!WikiCreole style//** || 30 29 || {{{`monospaced (''other markup ignored'')`}}} || \ 31 30 || `monospaced (''other markup ignored'')` || 32 || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \33 || **bold**, //italic//, **//!WikiCreole style//** ||34 31 |----------------------------------------------------------- 35 32 ||= [#Headings Headings] =||\ 36 33 {{{#!td 37 34 {{{ 38 == Level 2 ==35 == Level 2 39 36 === Level 3 ^([#hn note])^ 40 37 }}} 41 38 }}} 42 39 {{{#!td style="padding-left: 2em" 43 == Level 2 ==40 == Level 2 44 41 === Level 3 ^([#hn note])^ 45 42 }}} … … 64 61 {{{#!td 65 62 {{{ 66 * bullet slist63 * bullet list 67 64 on multiple lines 68 65 1. nested list … … 72 69 }}} 73 70 {{{#!td 74 * bullet slist71 * bullet list 75 72 on multiple lines 76 73 1. nested list … … 97 94 {{{ 98 95 {{{ 99 multiple lines, ''no wiki'' 96 multiple lines, ''no wiki'', 100 97 white space respected 101 98 }}} … … 104 101 {{{#!td 105 102 {{{ 106 multiple lines, ''no wiki'' 103 multiple lines, ''no wiki'', 107 104 white space respected 108 105 }}} … … 160 157 || `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\ 161 158 || #1 (ticket), [1] (changeset), {1} (report) || 162 || `ticket:1, ticket:1#comment:1 ` ||\163 || 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 || 164 161 || `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\ 165 162 || Ticket [ticket:1], [ticket:1 ticket one] || … … 182 179 || `!wiki:WikiFormatting`, `!WikiFormatting` ||\ 183 180 || !wiki:WikiFormatting, !WikiFormatting || 184 || {{{`}}}`{{{-}}}`{{{`}}}` triple curly brackets`||\181 || [[html(<code>`{{{-}}}` triple curly brackets</code>)]] ||\ 185 182 || `{{{-}}}` triple curly brackets || 186 183 |----------------------------------------------------------- … … 196 193 {{{#!td 197 194 {{{ 198 {{{ 199 #!div style="font-size: 80%" 195 {{{#!div style="font-size: 80%" 200 196 Code highlighting: 201 197 {{{#!python … … 206 202 }}} 207 203 {{{#!td style="padding-left: 2em" 208 {{{ 209 #!div style="font-size: 80%" 204 {{{#!div style="font-size: 80%" 210 205 Code highlighting: 211 206 {{{#!python … … 223 218 }}} 224 219 }}} 225 {{{#!td style="padding-left: 2em" 226 {{{#!comment 227 Note to Editors: ... 228 }}} 229 }}} 220 || ''(comment is shown in edit mode only)'' || 230 221 |----------------------------------------------------------- 231 222 ||= [#Miscellaneous Miscellaneous] =||\ … … 243 234 }}} 244 235 245 246 == Font Styles == 236 == Font Styles 247 237 248 238 The Trac wiki supports the following font styles: … … 287 277 Notes: 288 278 * `{{{...}}}` 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. 289 * {{{ ! }}} 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.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. 290 280 * all the font styles marks have to be used in opening/closing pairs, 291 and they must nest properly (in particular, an `''` italic can't be paired 292 with a `//` one, and `'''` can't be paired with `**`) 293 294 295 == Headings == 296 297 You can create heading by starting a line with one up to six ''equal'' characters ("=") 298 followed by a single space and the headline text. 281 and they must nest properly; in particular, an `''` italic can't be paired 282 with a `//` one, and `'''` can't be paired with `**`. 283 284 == Headings 285 286 You can create a heading by starting a line with one up to six ''equal'' characters (`=`) followed by a single space and the headline text. 299 287 300 288 [=#hn] 301 The headline text can be followed by the same number of "=" characters, but this is no longer mandatory.289 The headline text can be followed by the same number of `=` characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`. 302 290 303 291 Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated. … … 324 312 }}} 325 313 326 == Paragraphs ==314 == Paragraphs 327 315 328 316 A new text paragraph is created whenever two blocks of text are separated by one or more empty lines. … … 352 340 }}} 353 341 354 == Lists ==342 == Lists 355 343 356 344 The wiki supports both ordered/numbered and unordered lists. 357 345 358 Example:359 346 ||= Wiki Markup =||= Display =|| 360 347 {{{#!td … … 408 395 }}} 409 396 410 411 == Definition Lists == 397 == Definition Lists 412 398 413 399 The wiki also supports definition lists. … … 433 419 Note that you need a space in front of the defined term. 434 420 435 436 == Preformatted Text == 421 == Preformatted Text 437 422 438 423 Block 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. … … 456 441 Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors. 457 442 458 == Blockquotes ==443 == Blockquotes 459 444 460 445 In order to mark a paragraph as blockquote, indent that paragraph with two spaces. … … 472 457 }}} 473 458 474 == Discussion Citations ==475 476 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, e -mail-like citation marks (">", ">>", etc.) may be used.459 == Discussion Citations 460 461 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (`>`, `>>`, etc.) may be used. 477 462 478 463 ||= Wiki Markup =||= Display =|| … … 492 477 }}} 493 478 494 495 == Tables ==496 === Simple Tables === 497 Simple tables can be created like this:479 == Tables 480 === Simple Tables 481 482 Simple tables can be created: 498 483 ||= Wiki Markup =||= Display =|| 499 484 {{{#!td … … 508 493 }}} 509 494 510 Cell headings can be specified by wrapping the content in a pair of '='characters.511 Note that the '=' characters have to stick to the cell separators, like this:495 Cell headings can be specified by wrapping the content in a pair of `=` characters. 496 Note that the `=` characters have to stick to the cell separators: 512 497 ||= Wiki Markup =||= Display =|| 513 498 {{{#!td … … 524 509 }}} 525 510 526 Finally, specifying an empty cell means that the next non empty cell will span the empty cells . For example:511 Finally, specifying an empty cell means that the next non empty cell will span the empty cells: 527 512 ||= Wiki Markup =||= Display =|| 528 513 {{{#!td … … 541 526 }}} 542 527 543 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:528 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: 544 529 ||= Wiki Markup =||= Display =|| 545 530 {{{#!td … … 566 551 }}} 567 552 568 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 .553 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: 569 554 570 555 ||= Wiki Markup =|| … … 584 569 }}} 585 570 586 === Complex Tables === 587 588 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]. 589 590 591 == Links == 592 593 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}. 571 === Complex Tables 572 573 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]. 574 575 == Links 576 577 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark (`!`), such as `!WikiPageLink`. 594 578 595 579 ||= Wiki Markup =||= Display =|| … … 622 606 }}} 623 607 624 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.608 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. 625 609 626 610 {{{#!td … … 643 627 }}} 644 628 645 '''Note''': the [trac:WikiCreole] style for links is quick to type and 646 certainly looks familiar as it's the one used on Wikipedia and in many 647 other wikis. Unfortunately it conflicts with the syntax for [#Macros macros]. 648 So in the rare case when you need to refer to a page which is named after 649 a macro (typical examples being TitleIndex, InterTrac and InterWiki), 650 by writing `[[TitleIndex]]` you will actually call the macro instead of linking 651 to the page. 652 653 == Trac Links == 629 '''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]. 630 So 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. 631 632 == Trac Links 654 633 655 634 Wiki 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: … … 681 660 There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers. 682 661 683 684 == Setting Anchors == 685 686 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: 662 == Setting Anchors 663 664 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, to uniquely identify a position in the document: 687 665 688 666 {{{ … … 690 668 }}} 691 669 692 This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above] . For example:670 This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]: 693 671 {{{ 694 672 == Long title == #title 695 673 }}} 696 674 697 It 's also very close to the syntax for the corresponding link to that anchor:675 It is also very close to the syntax for the corresponding link to that anchor: 698 676 {{{ 699 677 [#point1] … … 702 680 Optionally, a label can be given to the anchor: 703 681 {{{ 704 [ [=#point1 '''Point 1''']]682 [=#point1 '''Point 1'''] 705 683 }}} 706 684 … … 724 702 }}} 725 703 726 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)^)]]`. 727 704 For 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)^)]]`. 728 705 729 706 == Escaping Links, WikiPageNames and other Markup == #Escaping 730 707 731 You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).708 You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark (`!`). 732 709 733 710 ||= Wiki Markup =||= Display =|| … … 754 731 }}} 755 732 756 == Images ==733 == Images 757 734 758 735 Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags. … … 778 755 See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.) 779 756 780 781 == Macros == 782 783 Macros are ''custom functions'' to insert dynamic content in a page. 757 == Macros 758 759 Macros are ''custom functions'' that insert dynamic content in a page. 784 760 785 761 ||= Wiki Markup =||= Display =|| … … 795 771 See WikiMacros for more information, and a list of installed macros. 796 772 797 The detailed help for a specific macro can also be obtained more directly by appending a "?"to the macro name.773 The detailed help for a specific macro can also be obtained more directly by appending a `?` to the macro name. 798 774 799 775 ||= Wiki Markup =||= Display =|| … … 807 783 }}} 808 784 809 810 == Processors == 785 == Processors 811 786 812 787 Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in … … 823 798 {{{#!td style="border: 0px" 824 799 {{{ 825 {{{ 826 #!html 800 {{{#!html 827 801 <h1 style="text-align: right; color: blue"> 828 802 HTML Test … … 833 807 {{{#!td valign="top" style="border: 0px" 834 808 835 {{{ 836 #!html 809 {{{#!html 837 810 <h1 style="text-align: right; color: blue">HTML Test</h1> 838 811 }}} … … 848 821 {{{#!td style="border: 0px" 849 822 {{{ 850 {{{ 851 #!python 823 {{{#!python 852 824 class Test: 853 825 … … 859 831 }}} 860 832 }}} 861 {{{ 862 #!td valign="top" style="border: 0px" 863 864 {{{ 865 #!python 833 {{{#!td valign="top" style="border: 0px" 834 835 {{{#!python 866 836 class Test: 867 837 def __init__(self): … … 910 880 }}} 911 881 }}} 912 {{{ 913 #!td valign="top" style="border: 0px" 882 {{{#!td valign="top" style="border: 0px" 914 883 915 884 {{{#!th rowspan=4 align=justify … … 945 914 See WikiProcessors for more information. 946 915 947 948 == Comments == 916 == Comments 949 917 950 918 Comments can be added to the plain text. These will not be rendered and will not display in any other format than plain text. … … 954 922 {{{ 955 923 Nothing to 956 {{{ 957 #!comment 924 {{{#!comment 958 925 Your comment for editors here 959 926 }}} 960 see ;-)927 see. 961 928 }}} 962 929 }}} 963 930 {{{#!td 964 931 Nothing to 965 {{{ 966 #!comment 932 {{{#!comment 967 933 Your comment for editors here 968 934 }}} 969 see ;-) 970 }}} 971 972 == Miscellaneous == 973 974 An horizontal line can be used to separated different parts of your page: 975 976 ||= Wiki Markup =||= Display =|| 977 {{{#!td 935 see. 936 }}} 937 938 == Miscellaneous 939 940 ||= Wiki Markup =||= Display =|| 941 {{{#!td 942 Horizontal line: 978 943 {{{ 979 944 Four or more dashes will be replaced 980 by a nhorizontal line (<HR>)945 by a horizontal line (<HR>) 981 946 ---- 982 947 See? … … 985 950 {{{#!td 986 951 Four or more dashes will be replaced 987 by a nhorizontal line (<HR>)952 by a horizontal line (<HR>) 988 953 ---- 989 954 See? … … 991 956 |---------------------------------- 992 957 {{{#!td 993 {{{ 994 "macro" style [[br]] line break 995 }}} 996 }}} 997 {{{#!td 998 "macro" style [[br]] line break 958 Two examples of line breaks: 959 {{{ 960 "macro" style [[BR]] line break 961 }}} 962 or: 963 {{{ 964 !WikiCreole style \\ line\\break 965 }}} 966 }}} 967 {{{#!td 968 "macro" style [[BR]] line break 969 970 !WikiCreole style \\ line\\break 999 971 }}} 1000 972 |---------------------------------- 1001 {{{#!td1002 {{{1003 !WikiCreole style \\ line\\break1004 }}}1005 }}}1006 {{{#!td1007 !WikiCreole style \\ line\\break1008 }}}