# Stash Latest (2.12) : Markdown syntax guide

Created by pwatson, last modified by rbarnes on Mar 24, 2014

By default, Stash uses Markdown as its markup language. You can use markdown in the following places:

- any pull request's descriptions or comments, or
- in README files (if they have the .md file extension).

Use Control-Shift-P or Command-Shift-P to preview your markdown.

## Markdown syntax

The page below contains examples of Markdown syntax. For a full list of all the Markdown syntax, consult the official documentation on John Gruber's Daring Fireball site.

### Headings

    # This is an H1
    ## This is an H2
    ###### This is an H6

##### On this page:

### Paragraphs

    Each paragraph begins on a new line. Simply press <return> for a new line.

    For example,
    like this.

    You'll need an empty line between a paragraph and any following markdown construct,
    such as an ordered or unordered list, for that to be rendered. Like this:

    * Item 1
    * Item 2

### Character styles

    *Italic characters*
    _Italic characters_
    **bold characters**
    __bold characters__

### Unordered list

    * Item 1
    * Item 2
    * Item 3
        * Item 3a
        * Item 3b
        * Item 3c

### Ordered list

    1. Step 1
    2. Step 2
    3. Step 3
        a. Step 3a
        b. Step 3b
        c. Step 3c

### List in list

    1. Step 1
    2. Step 2
    3. Step 3
        * Item 3a
        * Item 3b
        * Item 3c

### Quotes or citations

    Introducing my quote:

    > Neque porro quisquam est qui
    > dolorem ipsum quia dolor sit amet,
    > consectetur, adipisci velit...

### Inline code characters

    Use the backtick to refer to a `function()`.

    There is a literal ``backtick (`)`` here.

### Code blocks

    Indent every line of the block by at least 4 spaces or 1 tab. Alternatively,
    you can also use 3 backtick quote marks before and after the block, like this:

    ```
    Text to appear as a code block.
    ```

    Within a code block, ampersands (&) and angle brackets (< and >)are automatically
    converted into HTML entities.

    This is a normal paragraph:
        This is a code block.
        With multiple lines.

### Links to external websites

    This is [an example](http://www.slate.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.

### Linking issue keys to JIRA

When you use JIRA issue keys (of the default format) in comments and pull request descriptions Stash automatically links them to the JIRA instance.

The default JIRA issue key format is two or more uppercase letters (`[A-Z][A-Z]+`), followed by a hyphen and the issue number, for example STASH-123.

### Images

Inline image syntax looks like this:

    ![Alt text](/path/to/image.jpg)
    ![Alt text](/path/to/image.png "Optional title attribute")
    ![Alt text](/url/to/image.jpg)

For example:

    ...
    ![Mockup for feature A](http://monosnap.com/image/bOcxxxxLGF.png)
    ...

Reference image links look like this:

    ![Alt text][id]

where 'id' is the name of a previously defined image reference, using syntax similar to link references:

    [id]: url/to/image.jpg "Optional title attribute"

For example:

    ...
    <--Collected image definitions-->
    [MockupA]: http://monosnap.com/image/bOcxxxxLGF.png "Screenshot of Feature A mockup"
    ...
    <!--Using an image reference-->
    ![Mockup for feature A][MockupA]
    ...

### Tables

    | Day     | Meal    | Price |
    | --------|---------|-------|
    | Monday  | pasta   | $6    |
    | Tuesday | chicken | $8    |

You can also use HTML...

Inline HTML

An example, to add a table:

    This is a regular paragraph.

    <table>
        <tr>
            <td>Foo</td>
        </tr>
    </table>

    This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level HTML tags. That is, you can’t use Markdown-style `*emphasis*` inside an HTML block.

See http://daringfireball.net/projects/markdown/syntax#html for more details.

## README files

From Stash 1.3, you can document a project right in the repository by creating .md or .txt files. If the ReadMe has the .md extension, any Markdown it contains gets rendered straight to the screen when viewed from the file list of the repository.

## Attachments:

STASH13_readmerendering.png (image/png)
STASH13_readmerendering.png (image/png)