phabricator/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:

  **bold** //italic// ##monospaced##
  = Large Header=
  == Smaller Header ==
  > Quoted Text
  D123 T123 rX123   # Link to Objects
  {D123} {T123}     # Link to Objects (Full Name)
  {F123}            # Embed Images
  [[wiki page]]     # Link to Phriction
  @username         # Mention a user
  Use "- " or "* " for list items.
  Use ``` or indent two spaces for code.
  Use %%% for a literal block.

= Basic Styling =

Format **basic text styles** like this:

  **bold text**
  //italic text//
  ##monospaced text##

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

= Layout =

Make **headers** like this:

  = Large Header =
  == Smaller Header ==
  ===== Very Small Header =====

This produces headers like the ones in this document.

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 "*".)

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 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/,>

= 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 is closed or a revision is committed).

= 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:

  {F92}         # Embed the image file F92

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

= 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 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]]!

You can also use this as an explicit syntax for other web links, either within
Phabricator or on the internet at large:

  [[/herald/transcript/ | Herald Transcripts]]
  [[http://www.boring-legal-documents.com/ | 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, linkify URLs, and preserve line breaks).