Documentation | 2025.1

# Markdown

You can use Markdown to add text styles to comments, review descriptions, and project overview pages. Swarm can also display Markdown files stored in the Helix Core Server.

- The Review Activity tab is rendered in GFM (Git Flavored Markdown).

- The User, Group, and Project page Activity tabs and the Activity page are rendered in Parsedown.

In this section:

- Common text styles
- Text styling example
- Markdown in comments and review descriptions
- Markdown in projects

## Common text styles

### Markdown renderers supported

Swarm uses GFM (Git Flavored Markdown) or Parsedown to render text styles. The renderer used depends on where you are entering your text in Swarm:

- Review comments and review descriptions support GFM (Git Flavored Markdown), see Basic writing and formatting syntax

- Project overview pages, changelist comments, and jobs page comments support Parsedown, see the Parsedown demo

### Common GFM and Parsedown styles

A number of the more common text styles are shown below:

- bold and italics can be specified with `**bold**` or `*italics*`.

- Unordered lists can be specified with asterisk (`*`) markers. Plus (`+`) and minus (`-`) signs also work:

      * This
      * That
      * Another

- Ordered lists can be specified with numbered markers:

      1. First
      2. Second
      3. Third

- Hypertext links can be specified with [Link text](http://address/page). If you don't need to add anchor text, then a URL in the text without any markup is linkified.
- You can mark inline text as code using `backticks`.

- You can also mark blocks of code using three backticks on a line, like:

      ```
      var text = "Some code text";
      alert(text);
      ```

- Headers can be defined using hash (#) marks.

      # Main heading
      ## Sub heading
      ### Lesser heading

- Images can be added as well. You can either provide the full Swarm view URL, or use a relative Swarm view URL to reference something in Swarm.

      ![alt text](https://swarm.company.com/view/depot/www/dev/images/jamgraph-jam.gif "Title Text")
      ![alt text](/view/depot/www/dev/images/jamgraph-jam.gif "Title Text")

  To find the Swarm view URL for an image file:

  1. From Swarm, click on the Files tab and navigate to the image file.
  2. Click on the image file so that it opens in the View tab.
  3. Click the Open button for the file to open the image in you browser.
  4. The URL in your browser address bar is the Swarm view URL for the image file.

- Link to a YouTube video using the Share --> COPY feature for the YouTube video. For example:

  [![alt text](https://img.youtube.com/vi/wimka8j4XBk/mqdefault.jpg)](https://youtu.be/wimka8j4XBk)

- Tables are supported by using pipe (|) separators between columns and colons (:) for justification.

      | Tables   | Look   | Like this |
      | -------- | ----:  | :-------: |
      | Left     | right  | center    |

- It is also possible to blockquote paragraphs using the greater than symbol (>).

      > Blockquotes can be displayed like this, using the
      > the greater than sign at the start of the line.

      Normal text resumes here.

## Text styling example

The following example shows how Markdown text can be used in a comment but it would display the same for a project overview page.

The source and the final result are shown:

- Source text
- Rendered view of Markdown text

### Source text

    *Comments* can include **Markdown** text, which allows basic styles to be applied to the text.

    You can have unordered lists, like this:
    * A line
    * Another line
      * A sub list
      * Again
    * Back again

    Or ordered lists:
    1. First
    2. Second
    3. Third

    It is possible to mark text as `code { like: this }` or to define a block of text as code:
    ```
    var i = 1;
    var j = 10;
    for (i = 1; j != i; i++) {
      print i * j;
    }
    ```

    You can also [create hyper links](http://www.perforce.com) which point to other places.

    Use the backslash character \ to escape Markdown syntax characters.
    You can escape the following characters:
    Asterisk \*
    Underscore \_
    Curly braces \{ \}
    Square brackets \[ \]
    Brackets \( \)
    Hash \#
    Plus \+
    Minus \-
    Period \.
    Exclamation point \!

### Rendered view of Markdown text

## Markdown in comments and review descriptions

- Try to avoid using styles like headers, images, and tables in comments, they can make comments harder to read this is especially true inline comments.

- Renderer supported:

  - Review comments and review descriptions support GFM (Git Flavored Markdown), see Basic writing and formatting syntax.

  - Changelist comments and jobs page comments support Parsedown, see the Parsedown demo.

Markdown content is displayed in comments and review descriptions, but Markdown support is limited to prevent execution of raw HTML and JavaScript content.

If you use Markdown styles in your comments and review descriptions, Swarm renders them when you save the changes. The same markdown is displayed in the Swarm HTML emails.

## Markdown in projects

If a project has a `README` markdown file in the root of its `MAIN` branch, that README markdown file is displayed as the overview page for the project.

By default, Markdown content is displayed on the project overview page but is limited to prevent the execution of raw HTML and JavaScript content. This can be configured by the Swarm administrator.

- Markdown support for displaying the project overview page can be disabled by your Swarm administrator, see Project readme.
- The level of Markdown support can be configured by your Swarm administrator, see Markdown.

If you need to change which branch is considered MAIN, and therefore from where the `README` is read from, see Mainline branch identification.

- Valid Markdown file extensions are: md, markdown, mdown, mkdn, mkd, mdwn, mdtxt, mdtext.

If more than one README file is found, Swarm displays the first one it finds based on the order above.

- The Project overview pages support Parsedown, see the Parsedown demo.

Your search for returned results