[Summary view] [Print] [Text view]

   1  @title Remarkup Reference
   2  @group userguide
   3  
   4  Explains how to make bold text; this makes your words louder so you can win
   5  arguments.
   6  
   7  = Overview =
   8  
   9  Phabricator uses a lightweight markup language called "Remarkup", similar to
  10  other lightweight markup languages like Markdown and Wiki markup.
  11  
  12  This document describes how to format text using Remarkup.
  13  
  14  = Quick Reference =
  15  
  16  All the syntax is explained in more detail below, but this is a quick guide to
  17  formatting text in Remarkup.
  18  
  19  These are inline styles, and can be applied to most text:
  20  
  21    **bold** //italic// `monospaced` ##monospaced## ~~deleted~~ __underlined__
  22    D123 T123 rX123           # Link to Objects
  23    {D123} {T123}             # Link to Objects (Full Name)
  24    {F123}                    # Embed Images
  25    {M123}                    # Embed Pholio Mock
  26    @username                 # Mention a User
  27    #project                  # Mention a Project
  28    [[wiki page]]             # Link to Phriction
  29    [[wiki page | name]]      # Named link to Phriction
  30    http://xyz/               # Link to web
  31    [[http://xyz/ | name]]    # Named link to web
  32    [name](http://xyz/)       # Alternate Link
  33  
  34  These are block styles, and must be separated from surrounding text by
  35  empty lines:
  36  
  37    = Large Header =
  38  
  39    == Smaller Header ==
  40  
  41    ## This is a Header As Well
  42  
  43    Also a Large Header
  44    ===================
  45  
  46    Also a Smaller Header
  47    ---------------------
  48  
  49    > Quoted Text
  50  
  51    Use `- ` or `* ` for bulleted lists, and `# ` for numbered lists.
  52    Use ``` or indent two spaces for code.
  53    Use %%% for a literal block.
  54    Use | ... | ... for tables.
  55  
  56  = Basic Styling =
  57  
  58  Format **basic text styles** like this:
  59  
  60    **bold text**
  61    //italic text//
  62    `monospaced text`
  63    ##monospaced text##
  64    ~~deleted text~~
  65    __underlined text__
  66  
  67  Those produce **bold text**, //italic text//, `monospaced text`, ##monospaced
  68  text##, ~~deleted text~~, and __underlined text__, respectively.
  69  
  70  = Layout =
  71  
  72  Make **headers** like this:
  73  
  74    = Large Header =
  75  
  76    == Smaller Header ==
  77  
  78    ===== Very Small Header =====
  79  
  80    Alternate Large Header
  81    ======================
  82  
  83    Alternate Smaller Header
  84    ------------------------
  85  
  86  You can optionally omit the trailing `=` signs -- that is, these are the same:
  87  
  88    == Smaller Header ==
  89  
  90    == Smaller Header
  91  
  92  This produces headers like the ones in this document. Make sure you have an
  93  empty line before and after the header.
  94  
  95  Make **lists** by beginning each item with a `-` or a `*`:
  96  
  97    lang=text
  98    - milk
  99    - eggs
 100    - bread
 101  
 102    * duck
 103    * duck
 104    * goose
 105  
 106  This produces a list like this:
 107  
 108    - milk
 109    - eggs
 110    - bread
 111  
 112  (Note that you need to put a space after the `-` or `*`.)
 113  
 114  You can make numbered lists with a `#` instead of `-` or `*`:
 115  
 116    # Articuno
 117    # Zapdos
 118    # Moltres
 119  
 120  You can also nest lists:
 121  
 122  ```- Body
 123    - Head
 124    - Arm
 125      - Elbow
 126      - Hand
 127        # Thumb
 128        # Index
 129        # Middle
 130        # Ring
 131        # Pinkie
 132    - Leg
 133      - Knee
 134      - Foot```
 135  
 136  ...which produces:
 137  
 138    - Body
 139    - Head
 140    - Arm
 141      - Elbow
 142      - Hand
 143        # Thumb
 144        # Index
 145        # Middle
 146        # Ring
 147        # Pinkie
 148    - Leg
 149      - Knee
 150      - Foot
 151  
 152  If you prefer, you can indent lists using multiple characters to show indent
 153  depth, like this:
 154  
 155  ```- Tree
 156  -- Branch
 157  --- Twig```
 158  
 159  As expected, this produces:
 160  
 161  - Tree
 162  -- Branch
 163  --- Twig
 164  
 165  You can add checkboxes to items by prefacing them with `[ ]` or `[X]`, like
 166  this:
 167  
 168  ```
 169    - [X] Preheat oven to 450 degrees.
 170    - [ ] Zest 35 lemons.
 171  ```
 172  
 173  When rendered, this produces:
 174  
 175    - [X] Preheat oven to 450 degrees.
 176    - [ ] Zest 35 lemons.
 177  
 178  Make **code blocks** by indenting two spaces:
 179  
 180    f(x, y);
 181  
 182  You can also use three backticks to enclose the code block:
 183  
 184    ```f(x, y);
 185    g(f);```
 186  
 187  You can specify a language for syntax highlighting with `lang=xxx`:
 188  
 189    lang=text
 190    lang=html
 191    <a href="#">...</a>
 192  
 193  This will highlight the block using a highlighter for that language, if one is
 194  available (in most cases, this means you need to configure Pygments):
 195  
 196    lang=html
 197    <a href="#">...</a>
 198  
 199  You can also use a `COUNTEREXAMPLE` header to show that a block of code is
 200  bad and shouldn't be copied:
 201  
 202    lang=text
 203    COUNTEREXAMPLE
 204    function f() {
 205      global $$variable_variable;
 206    }
 207  
 208  This produces a block like this:
 209  
 210    COUNTEREXAMPLE
 211    function f() {
 212      global $$variable_variable;
 213    }
 214  
 215  You can use `lines=N` to limit the vertical size of a chunk of code, and
 216  `name=some_name.ext` to give it a name. For example, this:
 217  
 218    lang=text
 219    lang=html, name=example.html, lines=12, counterexample
 220    ...
 221  
 222  ...produces this:
 223  
 224    lang=html, name=example.html, lines=12, counterexample
 225    <p>Apple</p>
 226    <p>Apricot</p>
 227    <p>Avocado</p>
 228    <p>Banana</p>
 229    <p>Bilberry</p>
 230    <p>Blackberry</p>
 231    <p>Blackcurrant</p>
 232    <p>Blueberry</p>
 233    <p>Currant</p>
 234    <p>Cherry</p>
 235    <p>Cherimoya</p>
 236    <p>Clementine</p>
 237    <p>Date</p>
 238    <p>Damson</p>
 239    <p>Durian</p>
 240    <p>Eggplant</p>
 241    <p>Elderberry</p>
 242    <p>Feijoa</p>
 243    <p>Gooseberry</p>
 244    <p>Grape</p>
 245    <p>Grapefruit</p>
 246    <p>Guava</p>
 247    <p>Huckleberry</p>
 248    <p>Jackfruit</p>
 249    <p>Jambul</p>
 250    <p>Kiwi fruit</p>
 251    <p>Kumquat</p>
 252    <p>Legume</p>
 253    <p>Lemon</p>
 254    <p>Lime</p>
 255    <p>Lychee</p>
 256    <p>Mandarine</p>
 257    <p>Mango</p>
 258    <p>Mangostine</p>
 259    <p>Melon</p>
 260  
 261  You can also use `NOTE:`, `WARNING:`, or `IMPORTANT:` to call out an important
 262   idea.
 263  
 264  NOTE: Best practices in proton pack operation include not crossing the streams.
 265  
 266  WARNING: Crossing the streams can result in total protonic reversal!
 267  
 268  IMPORTANT: Don't cross the streams!
 269  
 270  In addition, you can use `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` to get the
 271  same effect but without `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` appearing in
 272  the rendered result. For example
 273  
 274  (NOTE) Dr. Egon Spengler is the best resource for additional proton pack
 275   questions.
 276  
 277  = Linking URIs =
 278  
 279  URIs are automatically linked: http://phabricator.org/
 280  
 281  If you have a URI with problematic characters in it, like
 282  "`http://comma.org/,`", you can surround it with angle brackets:
 283  
 284    <http://comma.org/,>
 285  
 286  This will force the parser to consume the whole URI: <http://comma.org/,>
 287  
 288  You can also use create named links, where you choose the displayed text. These
 289  work within Phabricator or on the internet at large:
 290  
 291    [[/herald/transcript/ | Herald Transcripts]]
 292    [[http://www.boring-legal-documents.com/ | exciting legal documents]]
 293  
 294  Markdown-style links are also supported:
 295  
 296    [Toil](http://www.trouble.com)
 297  
 298  = Linking to Objects =
 299  
 300  You can link to Phabricator objects, such as Differential revisions, Diffusion
 301  commits and Maniphest tasks, by mentioning the name of an object:
 302  
 303    D123          # Link to Differential revision D123
 304    rX123         # Link to SVN commit 123 from the "X" repository
 305    rXaf3192cd5   # Link to Git commit "af3192cd5..." from the "X" repository.
 306                  # You must specify at least 7 characters of the hash.
 307    T123          # Link to Maniphest task T123
 308  
 309  You can also link directly to a comment in Maniphest and Differential:
 310  
 311    T123#4        # Link to comment #4 of T123
 312  
 313  See the Phabricator configuraton setting `remarkup.ignored-object-names` to
 314  modify this behavior.
 315  
 316  = Embedding Objects
 317  
 318  You can also generate full-name references to some objects by using braces:
 319  
 320    {D123}        # Link to Differential revision D123 with the full name
 321    {T123}        # Link to Maniphest task T123 with the full name
 322  
 323  These references will also show when an object changes state (for instance, a
 324  task or revision is closed). Some types of objects support rich embedding.
 325  
 326  == Linking to Project Tags
 327  
 328  Projects can be linked to with the use of a hashtag `#`. This works by default
 329  using the name of the Project (lowercase, underscored). Additionally you
 330  can set multiple additional hashtags by editing the Project details.
 331  
 332    #qa, #quality_assurance
 333  
 334  == Embedding Mocks (Pholio)
 335  
 336  You can embed a Pholio mock by using braces to refer to it:
 337  
 338    {M123}
 339  
 340  By default the first four images from the mock set are displayed. This behavior
 341  can be overridden with the **image** option. With the **image** option you can
 342  provide one or more image IDs to display.
 343  
 344  You can set the image (or images) to display like this:
 345  
 346    {M123, image=12345}
 347    {M123, image=12345 & 6789}
 348  
 349  == Embedding Pastes
 350  
 351  You can embed a Paste using braces:
 352  
 353    {P123}
 354  
 355  You can adjust the embed height with the `lines` option:
 356  
 357    {P123, lines=15}
 358  
 359  You can highlight specific lines with the `highlight` option:
 360  
 361    {P123, highlight=15}
 362    {P123, highlight="23-25, 31"}
 363  
 364  == Embedding Images
 365  
 366  You can embed an image or other file by using braces to refer to it:
 367  
 368    {F123}
 369  
 370  In most interfaces, you can drag-and-drop an image from your computer into the
 371  text area to upload and reference it.
 372  
 373  Some browsers (e.g. Chrome) support uploading an image data just by pasting them
 374  from clipboard into the text area.
 375  
 376  You can set file display options like this:
 377  
 378    {F123, layout=left, float, size=full, alt="a duckling"}
 379  
 380  Valid options are:
 381  
 382    - **layout** left (default), center, right, inline, link (render a link
 383      instead of a thumbnail for images)
 384    - **float** If layout is set to left or right, the image will be floated so
 385      text wraps around it.
 386    - **size** thumb (default), full
 387    - **name** with `layout=link` or for non-images, use this name for the link
 388      text
 389    - **width** Scale image to a specific width.
 390    - **height** Scale image to a specific height.
 391    - **alt** Provide alternate text for assistive technologies.
 392  
 393  == Embedding Countdowns
 394  
 395  You can embed a countdown by using braces:
 396  
 397    {C123}
 398  
 399  = Quoting Text =
 400  
 401  To quote text, preface it with an `>`:
 402  
 403    > This is quoted text.
 404  
 405  This appears like this:
 406  
 407  > This is quoted text.
 408  
 409  = Embedding Media =
 410  
 411  If you set a configuration flag, you can embed media directly in text:
 412  
 413    - **remarkup.enable-embedded-youtube**: allows you to paste in YouTube videos
 414      and have them render inline.
 415  
 416  This option is disabled by default because it has security and/or
 417  silliness implications. Carefully read the description before enabling it.
 418  
 419  = Image Macros =
 420  
 421  You can upload image macros (More Stuff -> Macro) which will replace text
 422  strings with the image you specify. For instance, you could upload an image of a
 423  dancing banana to create a macro named "peanutbutterjellytime", and then any
 424  time you type that string on a separate line it will be replaced with the image
 425  of a dancing banana.
 426  
 427  = Memes =
 428  
 429  You can also use image macros in the context of memes. For example, if you
 430  have an image macro named `grumpy`, you can create a meme by doing the
 431  following:
 432  
 433    {meme, src = grumpy, above = toptextgoeshere, below = bottomtextgoeshere}
 434  
 435  By default, the font used to create the text for the meme is `tuffy.ttf`. For
 436  the more authentic feel of `impact.ttf`, you simply have to place the Impact
 437  TrueType font in the Phabricator subfolder `/resources/font/`. If Remarkup
 438  detects the presence of `impact.ttf`, it will automatically use it.
 439  
 440  = Mentioning Users =
 441  
 442  In Differential and Maniphest, you can mention another user by writing:
 443  
 444    @username
 445  
 446  When you submit your comment, this will add them as a CC on the revision or task
 447  if they aren't already CC'd.
 448  
 449  Icons
 450  =====
 451  
 452  You can add icons to comments using the `{icon ...}` syntax. For example:
 453  
 454    {icon camera}
 455  
 456  This renders: {icon camera}
 457  
 458  You can select a color for icons:
 459  
 460    {icon camera color=blue}
 461  
 462  This renders: {icon camera color=blue}
 463  
 464  For a list of available icons and colors, check the UIExamples application.
 465  (The icons are sourced from
 466  [[ http://fortawesome.github.io/Font-Awesome/ | FontAwesome ]], so you can also
 467  browse the collection there.)
 468  
 469  
 470  = Phriction Documents =
 471  
 472  You can link to Phriction documents with a name or path:
 473  
 474    Make sure you sign and date your [[legal/Letter of Marque and Reprisal]]!
 475  
 476  With a pipe (`|`), you can retitle the link. Use this to mislead your
 477  opponents:
 478  
 479    Check out these [[legal/boring_documents/ | exciting legal documents]]!
 480  
 481  = Literal Blocks =
 482  
 483  To place text in a literal block use `%%%`:
 484  
 485    %%%Text that won't be processed by remarkup
 486    [[http://www.example.com | example]]
 487    %%%
 488  
 489  Remarkup will not process the text inside of literal blocks (other than to
 490  escape HTML and preserve line breaks).
 491  
 492  = Tables =
 493  
 494  Remarkup supports simple table syntax. For example, this:
 495  
 496    | Fruit  | Color  | Price   | Peel?
 497    | -----  | -----  | -----   | -----
 498    | Apple  | red    | `$0.93` | no
 499    | Banana | yellow | `$0.19` | **YES**
 500  
 501  ...produces this:
 502  
 503  | Fruit  | Color  | Price   | Peel?
 504  | -----  | -----  | -----   | -----
 505  | Apple  | red    | `$0.93` | no
 506  | Banana | yellow | `$0.19` | **YES**
 507  
 508  Remarkup also supports a simplified HTML table syntax. For example, this:
 509  
 510    <table>
 511      <tr>
 512        <th>Fruit</th>
 513        <th>Color</th>
 514        <th>Price</th>
 515        <th>Peel?</th>
 516      </tr>
 517      <tr>
 518        <td>Apple</td>
 519        <td>red</td>
 520        <td>`$0.93`</td>
 521        <td>no</td>
 522      </tr>
 523      <tr>
 524        <td>Banana</td>
 525        <td>yellow</td>
 526        <td>`$0.19`</td>
 527        <td>**YES**</td>
 528      </tr>
 529    </table>
 530  
 531  ...produces this:
 532  
 533  <table>
 534    <tr>
 535      <th>Fruit</th>
 536      <th>Color</th>
 537      <th>Price</th>
 538      <th>Peel?</th>
 539    </tr>
 540    <tr>
 541      <td>Apple</td>
 542      <td>red</td>
 543      <td>`$0.93`</td>
 544      <td>no</td>
 545    </tr>
 546    <tr>
 547      <td>Banana</td>
 548      <td>yellow</td>
 549      <td>`$0.19`</td>
 550      <td>**YES**</td>
 551    </tr>
 552  </table>
 553  
 554  Some general notes about this syntax:
 555  
 556    - your tags must all be properly balanced;
 557    - your tags must NOT include attributes (`<td>` is OK, `<td style="...">` is
 558      not);
 559    - you can use other Remarkup rules (like **bold**, //italics//, etc.) inside
 560      table cells.
 561  
 562  Navigation Sequences
 563  ====================
 564  
 565  You can use `{nav ...}` to render a stylized navigation sequence when helping
 566  someone to locate something. This can be useful when writing documentation.
 567  For example, you could give someone directions to purchase lemons:
 568  
 569  {nav icon=home, name=Home >
 570  Grocery Store >
 571  Produce Section >
 572  icon=lemon-o, name=Lemons}
 573  
 574  To render this example, use this markup:
 575  
 576  ```
 577  {nav icon=home, name=Home >
 578  Grocery Store >
 579  Produce Section >
 580  icon=lemon-o, name=Lemons}
 581  ```
 582  
 583  In general:
 584  
 585    - Separate sections with `>`.
 586    - Each section can just have a name to add an element to the navigation
 587      sequence, or a list of key-value pairs.
 588    - Supported keys are `icon`, `name`, `type` and `href`.
 589    - The `type` option can be set to `instructions` to indicate that an element
 590      is asking the user to make a choice or follow specific instructions.
 591  
 592  = Fullscreen Mode =
 593  
 594  Remarkup editors provide a fullscreen composition mode. This can make it easier
 595  to edit large blocks of text, or improve focus by removing distractions. You can
 596  exit **Fullscreen** mode by clicking the button again or by pressing escape.