phorge-phorge/src/docs/userguide/remarkup.diviner

@title Remarkup Reference
@group userguide

Explains how to make bold text; this makes your words louder so you can win
arguments.

= Overview =

Phabricator uses a lightweight markup language called "Remarkup", similar to
other lightweight markup langauges like Markdown and Wiki markup.

This document describes how to format text using Remarkup.

= Quick Reference =

All the syntax is explained in more detail below, but this is a quick guide to
formatting text in Remarkup.

These are inline styles, and can be applied to most text:

  **bold** //italic// ##monospaced## `monospaced` ~~deleted~~
  D123 T123 rX123           # Link to Objects
  {D123} {T123}             # Link to Objects (Full Name)
  {F123}                    # Embed Images
  @username                 # Mention a user
  [[wiki page]]             # Link to Phriction
  [[wiki page | name]]      # Named link to Phriction
  http://xyz/               # Link to web
  [[http://xyz/ | name]]    # Named link to web


These are block styles, and must be separated from surrounding text by
empty lines:

  = Large Header =
  == Smaller Header ==
  > Quoted Text
  Use "- " or "* " for bulleted lists, and "# " for numbered lists.
  Use ``` or indent two spaces for code.
  Use %%% for a literal block.
  Use <table>...</table> for tables.

= Basic Styling =

Format **basic text styles** like this:

  **bold text**
  //italic text//
  ##monospaced text##
  `monospaced text`
  ~~deleted text~~

Those produce **bold text**, //italic text//, ##monospaced text##,
`monospaced text` and ~~deleted text~~, respectively.

= Layout =

Make **headers** like this:

  = Large Header =

  == Smaller Header ==

  ===== Very Small Header =====

You can optionally omit the trailing "=" signs -- that is, these are the same:

  == Smaller Header ==

  == Smaller Header

This produces headers like the ones in this document. Make sure you have an
empty line before and after the header.

Make **lists** by beginning each item with a "-" or a "*":

  lang=text
  - milk
  - eggs
  - bread

  * duck
  * duck
  * goose

This produces a list like this:

  - milk
  - eggs
  - bread

(Note that you need to put a space after the "-" or "*".)

You can make numbered lists with a "#" instead of "-" or "*":

  # Articuno
  # Zapdos
  # Moltres

You can also nest lists:

```- Body
  - Head
  - Arm
    - Elbow
    - Hand
      # Thumb
      # Index
      # Middle
      # Ring
      # Pinkie
  - Leg
    - Knee
    - Foot```

...which produces:

  - Body
  - Head
  - Arm
    - Elbow
    - Hand
      # Thumb
      # Index
      # Middle
      # Ring
      # Pinkie
  - Leg
    - Knee
    - Foot

If you prefer, you can indent lists using multiple characters to show indent
depth, like this:

```- Tree
-- Branch
--- Twig```

As expected, this produces:

- Tree
-- Branch
--- Twig

Make **code blocks** by indenting two spaces:

  f(x, y);

You can also use three backticks to enclose the code block:

  ```f(x, y);
  g(f);```

You can specify a language for syntax highlighting with "lang=xxx":

  lang=text
  lang=html
  <a href="#">...</a>

This will highlight the block using a highlighter for that language, if one is
available (in most cases, this means you need to configure Pygments):

  lang=html
  <a href="#">...</a>

You can also use a "COUNTEREXAMPLE" header to show that a block of code is
bad and shouldn't be copied:

  lang=text
  COUNTEREXAMPLE
  function f() {
    global $$variable_variable;
  }

This produces a block like this:

  COUNTEREXAMPLE
  function f() {
    global $$variable_variable;
  }

You can use ##lines=N## to limit the vertical size of a chunk of code, and
##name=some_name.ext## to give it a name. For example, this:

  lang=text
  lang=html, name=example.html, lines=12, counterexample
  ...

...produces this:

  lang=html, name=example.html, lines=12, counterexample
  <p>Apple</p>
  <p>Apricot</p>
  <p>Avocado</p>
  <p>Banana</p>
  <p>Bilberry</p>
  <p>Blackberry</p>
  <p>Blackcurrant</p>
  <p>Blueberry</p>
  <p>Currant</p>
  <p>Cherry</p>
  <p>Cherimoya</p>
  <p>Clementine</p>
  <p>Date</p>
  <p>Damson</p>
  <p>Durian</p>
  <p>Eggplant</p>
  <p>Elderberry</p>
  <p>Feijoa</p>
  <p>Gooseberry</p>
  <p>Grape</p>
  <p>Grapefruit</p>
  <p>Guava</p>
  <p>Huckleberry</p>
  <p>Jackfruit</p>
  <p>Jambul</p>
  <p>Kiwi fruit</p>
  <p>Kumquat</p>
  <p>Legume</p>
  <p>Lemon</p>
  <p>Lime</p>
  <p>Lychee</p>
  <p>Mandarine</p>
  <p>Mango</p>
  <p>Mangostine</p>
  <p>Melon</p>

You can also use "NOTE:" to call out an important idea.

NOTE: Don't cross the streams!

= Linking URIs =

URIs are automatically linked: http://phabricator.org/

If you have a URI with problematic characters in it, like
"##http://comma.org/,##", you can surround it with angle brackets:

  <http://comma.org/,>

This will force the parser to consume the whole URI: <http://comma.org/,>

You can also use create named links, where you choose the displayed text. These
work within Phabricator or on the internet at large:

  [[/herald/transcript/ | Herald Transcripts]]
  [[http://www.boring-legal-documents.com/ | exciting legal documents]]

= Linking to Objects =

You can link to Differential revisions, Diffusion commits and Maniphest tasks
by mentioning the name of an object:

  D123          # Link to Differential revision D123
  rX123         # Link to SVN commit 123 from the "X" repository
  rXaf3192cd5   # Link to Git commit "af3192cd5..." from the "X" repository.
                # You must specify at least 7 characters of the hash.
  T123          # Link to Maniphest task T123

You can also link directly to a comment in Maniphest and Differential:

  T123#4        # Link to comment #4 of T123

You can also generate full-name references to some objects by using braces:

  {D123}        # Link to Differential revision D123 with the full name
  {T123}        # Link to Maniphest task T123 with the full name

These references will also show when an object changes state (for instance, a
task or revision is closed).

= Quoting Text =

To quote text, preface it with an ">":

  > This is quoted text.

This appears like this:

> This is quoted text.

= Embedding Images =

You can embed an image by using braces to refer to it:

  {F123}         # Embed the image file F123

In most interfaces, you can drag-and-drop an image from your computer into the
text area to upload and reference it.

Some browsers (e.g. Chrome) support uploading an image data just by pasting them
from clipboard into the text area.

You can set file display options like this:

  {F123, layout=left, float, size=full}

Valid options are:

  - **layout** left (default), center, right, inline, link (render a link
    instead of a thumbnail for images)
  - **float** If layout is set to left or right, the image will be floated so
    text wraps around it.
  - **size** thumb (default), full
  - **name** with `layout=link` or for non-images, use this name for the link
    text

= Embedding Media =

If you set configuration flags, you can embed media directly in text:

  - **files.enable-proxy**: allows you to paste in image URLs and have them
    render inline.
  - **remarkup.enable-embedded-youtube**: allows you to paste in YouTube videos
    and have them render inline.

These options are disabled by default because they have security and/or
silliness implications, read their descriptions in ##default.conf.php## before
enabling them.

= Image Macros =

You can upload image macros (Files -> Image Macros) which will replace text
strings with the image you specify. For instance, you could upload an image of a
dancing banana to create a macro named "peanutbutterjellytime", and then any
time you type that string on a separate line it will be replaced with the image
of a dancing banana.

= Mentioning Users =

In Differential and Maniphest, you can mention another user by writing:

  @username

When you submit your comment, this will add them as a CC on the revision or task
if they aren't already CC'd.

= Phriction Documents =

You can link to Phriction documents with a name or path:

  Make sure you sign and date your [[legal/Letter of Marque and Reprisal]]!

With a pipe (##|##), you can retitle the link. Use this to mislead your
opponents:

  Check out these [[legal/boring_documents/ | exciting legal documents]]!

= Literal Blocks =

To place text in a literal block use "%%%":

  %%%Text that won't be processed by remarkup
  [[http://www.example.com | example]]
  %%%

Remarkup will not process the text inside of literal blocks (other than to
escape HTML and preserve line breaks).

= Tables =

Remarkup supports a simplified HTML table syntax. For example, this:

  <table>
    <tr>
      <th>Fruit</th>
      <th>Color</th>
      <th>Price</th>
      <th>Peel?</th>
    </tr>
    <tr>
      <td>Apple</td>
      <td>red</td>
      <td>`$0.93`</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Banana</td>
      <td>yellow</td>
      <td>`$0.19`</td>
      <td>**YES**</td>
    </tr>
  </table>

...produces this:

<table>
  <tr>
    <th>Fruit</th>
    <th>Color</th>
    <th>Price</th>
    <th>Peel?</th>
  </tr>
  <tr>
    <td>Apple</td>
    <td>red</td>
    <td>`$0.93`</td>
    <td>no</td>
  </tr>
  <tr>
    <td>Banana</td>
    <td>yellow</td>
    <td>`$0.19`</td>
    <td>**YES**</td>
  </tr>
</table>

Some general notes about this syntax:

  - your tags must all be properly balanced;
  - your tags must NOT include attributes (`<td>` is OK, `<td style="...">` is
    not);
  - you can use other Remarkup rules (like **bold**, //italics//, etc.) inside
    table cells.