Changes between Version 3 and Version 4 of WikiFormatting
- Timestamp:
- Jan 13, 2020, 11:53:00 PM (5 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WikiFormatting
v3 v4 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: … … 264 254 * **also bold**, //italic as well//, 265 255 and **'' bold italic **'' //(since 0.12)// 256 * [[span(style=color: #FF0000, a red text )]] 266 257 }}} 267 258 }}} … … 281 272 * **also bold**, //italic as well//, 282 273 and **'' bold italic **'' //(since 0.12)// 274 * [[span(style=color: #FF0000, a red text )]] 283 275 }}} 284 276 285 277 Notes: 286 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. 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.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. 288 280 * 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 290 with a `//` one, and `'''` can't be paired with `**`) 291 292 293 == Headings == 294 295 You can create heading by starting a line with one up to six ''equal'' characters ("=") 296 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. 297 287 298 288 [=#hn] 299 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`. 300 290 301 291 Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated. … … 322 312 }}} 323 313 324 == Paragraphs ==314 == Paragraphs 325 315 326 316 A new text paragraph is created whenever two blocks of text are separated by one or more empty lines. … … 350 340 }}} 351 341 352 == Lists ==342 == Lists 353 343 354 344 The wiki supports both ordered/numbered and unordered lists. 355 345 356 Example:357 346 ||= Wiki Markup =||= Display =|| 358 347 {{{#!td … … 406 395 }}} 407 396 408 409 == Definition Lists == 397 == Definition Lists 410 398 411 399 The wiki also supports definition lists. … … 431 419 Note that you need a space in front of the defined term. 432 420 433 434 == Preformatted Text == 421 == Preformatted Text 435 422 436 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. … … 454 441 Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors. 455 442 456 == Blockquotes ==443 == Blockquotes 457 444 458 445 In order to mark a paragraph as blockquote, indent that paragraph with two spaces. … … 470 457 }}} 471 458 472 == Discussion Citations ==473 474 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. 475 462 476 463 ||= Wiki Markup =||= Display =|| … … 490 477 }}} 491 478 492 493 == Tables ==494 === Simple Tables === 495 Simple tables can be created like this:479 == Tables 480 === Simple Tables 481 482 Simple tables can be created: 496 483 ||= Wiki Markup =||= Display =|| 497 484 {{{#!td … … 506 493 }}} 507 494 508 Cell headings can be specified by wrapping the content in a pair of '='characters.509 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: 510 497 ||= Wiki Markup =||= Display =|| 511 498 {{{#!td … … 522 509 }}} 523 510 524 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: 525 512 ||= Wiki Markup =||= Display =|| 526 513 {{{#!td … … 539 526 }}} 540 527 541 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: 542 529 ||= Wiki Markup =||= Display =|| 543 530 {{{#!td … … 564 551 }}} 565 552 566 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: 567 554 568 555 ||= Wiki Markup =|| … … 582 569 }}} 583 570 584 === Complex Tables === 585 586 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]. 587 588 589 == Links == 590 591 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`. 592 578 593 579 ||= Wiki Markup =||= Display =|| … … 620 606 }}} 621 607 622 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. 623 609 624 610 {{{#!td … … 641 627 }}} 642 628 643 '''Note''': the [trac:WikiCreole] style for links is quick to type and 644 certainly looks familiar as it's the one used on Wikipedia and in many 645 other wikis. Unfortunately it conflicts with the syntax for [#Macros macros]. 646 So in the rare case when you need to refer to a page which is named after 647 a macro (typical examples being TitleIndex, InterTrac and InterWiki), 648 by writing `[[TitleIndex]]` you will actually call the macro instead of linking 649 to the page. 650 651 == 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 652 633 653 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: … … 679 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. 680 661 681 682 == Setting Anchors == 683 684 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: 685 665 686 666 {{{ … … 688 668 }}} 689 669 690 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]: 691 671 {{{ 692 672 == Long title == #title 693 673 }}} 694 674 695 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: 696 676 {{{ 697 677 [#point1] … … 700 680 Optionally, a label can be given to the anchor: 701 681 {{{ 702 [ [=#point1 '''Point 1''']]682 [=#point1 '''Point 1'''] 703 683 }}} 704 684 … … 722 702 }}} 723 703 724 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)^)]]`. 725 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)^)]]`. 726 705 727 706 == Escaping Links, WikiPageNames and other Markup == #Escaping 728 707 729 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 (`!`). 730 709 731 710 ||= Wiki Markup =||= Display =|| … … 737 716 {{{ 738 717 Various forms of escaping for list markup: 739 `-`escaped minus sign \\740 ``1. escaped number \\741 {{{*}}}escaped asterisk sign718 ^^- escaped minus sign \\ 719 ^^1. escaped number \\ 720 ^^* escaped asterisk sign 742 721 }}} 743 722 }}} … … 747 726 748 727 Various forms of escaping for list markup: 749 `-`escaped minus sign \\750 ``1. escaped number \\751 {{{*}}}escaped asterisk sign752 }}} 753 754 == Images ==728 ^^- escaped minus sign \\ 729 ^^1. escaped number \\ 730 ^^* escaped asterisk sign 731 }}} 732 733 == Images 755 734 756 735 Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags. … … 776 755 See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.) 777 756 778 779 == Macros == 780 781 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. 782 760 783 761 ||= Wiki Markup =||= Display =|| … … 793 771 See WikiMacros for more information, and a list of installed macros. 794 772 795 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. 796 774 797 775 ||= Wiki Markup =||= Display =|| … … 805 783 }}} 806 784 807 808 == Processors == 785 == Processors 809 786 810 787 Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in … … 821 798 {{{#!td style="border: 0px" 822 799 {{{ 823 {{{ 824 #!html 800 {{{#!html 825 801 <h1 style="text-align: right; color: blue"> 826 802 HTML Test … … 831 807 {{{#!td valign="top" style="border: 0px" 832 808 833 {{{ 834 #!html 809 {{{#!html 835 810 <h1 style="text-align: right; color: blue">HTML Test</h1> 836 811 }}} … … 846 821 {{{#!td style="border: 0px" 847 822 {{{ 848 {{{ 849 #!python 823 {{{#!python 850 824 class Test: 851 825 … … 857 831 }}} 858 832 }}} 859 {{{ 860 #!td valign="top" style="border: 0px" 861 862 {{{ 863 #!python 833 {{{#!td valign="top" style="border: 0px" 834 835 {{{#!python 864 836 class Test: 865 837 def __init__(self): … … 908 880 }}} 909 881 }}} 910 {{{ 911 #!td valign="top" style="border: 0px" 882 {{{#!td valign="top" style="border: 0px" 912 883 913 884 {{{#!th rowspan=4 align=justify … … 943 914 See WikiProcessors for more information. 944 915 945 946 == Comments == 916 == Comments 947 917 948 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. … … 952 922 {{{ 953 923 Nothing to 954 {{{ 955 #!comment 924 {{{#!comment 956 925 Your comment for editors here 957 926 }}} 958 see ;-)927 see. 959 928 }}} 960 929 }}} 961 930 {{{#!td 962 931 Nothing to 963 {{{ 964 #!comment 932 {{{#!comment 965 933 Your comment for editors here 966 934 }}} 967 see ;-) 968 }}} 969 970 == Miscellaneous == 971 972 An horizontal line can be used to separated different parts of your page: 973 974 ||= Wiki Markup =||= Display =|| 975 {{{#!td 935 see. 936 }}} 937 938 == Miscellaneous 939 940 ||= Wiki Markup =||= Display =|| 941 {{{#!td 942 Horizontal line: 976 943 {{{ 977 944 Four or more dashes will be replaced 978 by a nhorizontal line (<HR>)945 by a horizontal line (<HR>) 979 946 ---- 980 947 See? … … 983 950 {{{#!td 984 951 Four or more dashes will be replaced 985 by a nhorizontal line (<HR>)952 by a horizontal line (<HR>) 986 953 ---- 987 954 See? … … 989 956 |---------------------------------- 990 957 {{{#!td 991 {{{ 992 "macro" style [[br]] line break 993 }}} 994 }}} 995 {{{#!td 996 "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 997 971 }}} 998 972 |---------------------------------- 999 {{{#!td1000 {{{1001 !WikiCreole style \\ line\\break1002 }}}1003 }}}1004 {{{#!td1005 !WikiCreole style \\ line\\break1006 }}}1007