How do I format text fields with Shotgun Markdown?

Shotgun currently supports Markdown and limited textile-to-HTML rendering in the following places:

  • Note bodies, Note replies, and Note email notifications, and
  • Ticket descriptions, Ticket replies, and Ticket email notifications.

Read “Formatting records and fields (manually and with rules)” to learn more about formatting cells and rows using background colors and font-styling.

Markdown support

Our Markdown implementation on Shotgun follows the widely-used "Github Flavored Markdown" (GFM) specification, with the addition of smart typographic quotes and some styling shorthand properties.


Inline-level styling

Italics and bold

Here, we differ from GFM by introducing more natural Slack-style shorthands:

Markdown Output
_italics_ italics
*bold* bold

But we have kept to the Markdown standard for longhand bold:

Markdown Output
__bold__ bold
**bold** bold


Markdown Output
This is ~~bad~~ good! This is bad good!


We'll auto-link URL patters we recognize for you, but if you want to specify a link text, use:

Markdown Output
[Example Site]( Example Site


Markdown Output
![Title/Alt Text](URL) cat.jpeg


Markdown Output
This is the `source` variable This is the source variable

Block-level styling


First paragraph

Second paragraph
with manual line-breaks

Third paragraph


Headings are preceded by # and a space:

# Title

## Subtitle

### 3rd level

#### 4th level

##### 5th level?!

###### All the way up to 6th level!!
Note: You can also format the 1st two levels with any number of = or -:



Lists are simple:

- One
- Two
- Three

Lists can be either ordered or unordered, using either numbers or -, and nested at will (with four spaces):

Markdown Output
1. First item
2. Second item
    with manual line-breaks
    - Item 2.1
    - Item 2.2
3. Third item
    - Item 3.1
        - Item 3.1.1
  1. First item
  2. Second item with manual line-breaks
    • Item 2.1
    • Item 2.2
  3. Third item
    • Item 3.1
    • Item 3.1.1

Task items

You can even write up quick task lists:

Markdown Output
- [x] I've completed this
- [x] ~~I've _really_ completed this!~~
- [ ] Still need to do this
    Remember to also check:
    - [ ] Bits
    - [X] Bobs
- [ ] and this


Markdown Output
A paragraph

> A blockquote with 
manual line-breaks > > A paragraph belonging to the blockquote
A paragraph
A blockquote with
manual line-breaks
Another paragraph


At the bare minimum, tables are created by defining a header row divided by -, with cells divided by |:

Markdown Output
| Keys | Values |
| ---- | ------ |
| id   | 1234   |
| code | Yoyo   |
Keys Values
id 1234
code Yoyo
Note: Any number of -'s will do, and tables don't have to be bordered by |. This is uglier but faster to write, and syntactically equivalent:

Cell alignment

You can specify alignment as follows:

Markdown Output
ID   | active? | description
---: | :-----: | :----------
1234 | Y       | Left-aligned
56   | N       | Text
ID active? description
1234 Y Left-aligned
56 N Text
Note: Any number of -'s will do. This is uglier but faster to write, and syntactically equivalent:
ID | active? | description
-: | :-: | :-
1234 | Y | Left-aligned
56 | N | Text

Code blocks

Code blocks are delimited by triple back-ticks on their own line:

['one', 2, THREE].forEach(function(i) {
    console.log("Index '%d'", i);

Code blocks can also define a language, which will activate syntax highlighting!

Markdown Output
['one', 2, THREE].forEach(function(i) {
    console.log("Index '%s'", i);
['one', 2, THREE].forEach(function(i) {
    console.log("Index '%s'", i);

Supported languages

Language name Alias
Apache apache, apacheconf
Bash bash, sh, zsh
CoffeeScript coffeescript, coffee, cson, iced
CPP cpp
CS cs
CSS css
Diff diff, patch
Dockerfile dockerfile, docker
Go go, golang
HTTP http, https
INI ini
Java java, jsp
JavaScript javascript, js, jsx
JSON json
Less less
Lua lua
Makefile makefile, mk, mak
Markdwon markdown, md, mkdown, mkd
NGINX nginx, nginxconf
Objective-C onjectivec, mm, objc, obj-c
Perl perl, pl, pm
PHP php, php3, php4, php5, php6
Python python, py, gyp
RIB rib
RSL rsl
Ruby ruby, rb, gemspec, podspec, thor, irb
SCSS scss
SQL sql
XML xml
YAML yml
Note: Let us know if your preferred language is missing!

Horizontal rules

Both --- or *** on their own line will produce a horizontal rule:

Two paragraphs


Separated by a line

Textile support

Shotgun also supports limited textile-to-HTML rendering.

Supported textile

Basic formatting

Type Syntax Description
Bold *Bold* Renders as…
Italics _Italics_ Renders as…
Blockquote (appears indented) Bq. Begin on this line, then resume on the next All text after the first double line break following a bq. token will be treated as textile markup.
Symbols (r) (tm) (c) Renders as…
® ™ ©


Type Syntax Description
Simple link to a web page is a great site! Renders as… is a great site!

Generally supports:
  • HTTP and HTTPS (with or without port numbers)
  • FTP
  • DMX
Relative link "This site's contact link":/contact Renders as…
This site’s contact link
Link with display text "Shotgun":
"Local link relative to base url":/support/contact
Email link should be contacted Renders as… should be contacted

Code fragments

Type Syntax Description
Fragments with no double line-breaks bc.
# Begin this way...
if @reflect.options.has_key?(:polymorphic)
All text after the first double line-break following a bc. token will be treated as textile markup.
Fragments that contain double line-breaks bc..
# Begin this way...
if @reflect.options.has_key?(:polymorphic)

     # then this...
To resume textile-to-html rendering after an extended bc. token, insert a bc. token right in front of the last line of code, then follow this with a double line-break.


Type Syntax Description
General syntax !image_url!  
Relatively linked images (uploaded to Shotgun) !/file_serve/attachment/2! In order for relative image links to work, it's best to use Shotgun's built-in URL routing for serving files (/file_serve/attachment/id), rather than the path to the file. For example:
URL-linked images !! Renders inline as...

example image

Escaping markup

Type Syntax Description
Escape until first line break notextile.
*this won't be bolded*

*this will be*
Renders as…
*this won’t be bolded*

this will be

Automatic Ticket and Revision linking

If you are using the Ticket entity, Tickets and Revisions referenced using this syntax will automatically be linked within the Ticket description and Replies on the Ticket. In addition, the "Related Tickets" and "Related Revisions" fields will be updated to contain any additional references found in the Ticket description and replies.

Syntax Description
Similar issue to #1234 but without the Javascript error. Renders as…
Similar issue to #1234 but without the Javascript error.
Something is up with r12345 that is breaking the dialog. Renders as…
Something is up with r12345 that is breaking the dialog.


  • 0
    Armando Ricalde

    Relatively linked images (uploaded to Shotgun)


    Is not working, I had to put the whole URL.

  • 0
    Benjamin Willenbring

    Good catch Armando!  But I'd recommend locating the file in question, and checking that the file serve link resolves to what you're using. As long as the file path is correct, you can use relative links to images in textile markup. See the 3rd example below.

    1. This works

    **Because we're using Shotgun's built-in URL routing to files
    . **



    **2. This also works

    **Because it's an absolute URL link to an image file.



    3. This also works

    Notice that the url below is the same as the one above - only it's a relative link. Also notice that the path to the file does not begin with /files. Rather, it begins with /storage/production/files/.



  • 0
    Marijn Eken

    It seems the notation for BOLD is, *this*, rather than **this**...

  • 0
    Armando Ricalde

    Same for Italics, just one underscore each side rather than two.

    It changed in some version update, and there is no Underscore anymore.

  • 0
    Jean-Paul LeDoux

    Just an FYI - the Harper's link used in the image url example is broken.

  • 0
    Maxim Doucet

    Hello, this is a heartfelt appeal to have inline code (monospace) text (for variables, paths, etc), besides code blocks which are already useful.

    In our studio, we (the devops team) are used to inline code in another ticketing system (redmine). Though to have a common workflow, we would like to switch to shotgun's ticketing system. And we miss inline code a lot :)

    Can we expect to see this one day?

  • 0
    François TARLIER

    bq. ; tickets ; revisions does not seems to work for me 

  • 0
    Maxim Doucet

    For tickets, the following syntax does work for me:


    Where "999" is the number of your ticket.

  • 0
    Patrick Wolf

    Just added this to a ticket and it didn't work:


    "Local link relative to base url":/support/contact

    Are links still supported?


  • 0
    Maxim Doucet

    As far as I know, Patrick, the url formatting is correct though hyperlinks will only appear in emails, not in the ticket (or ticket comment) itself.

    This text markup/formatting system is somehow depressing :)

    FYI, I opened a ticket linked to this (#30891 for you admins), and hopefully it will be fixed one day even if I had no ETA. My "dream" would be to have markdown implemented (instead of the limited textile markup). This way we (or only "I", really?) have a common syntax in github, gitlab, shotgun, your-favorite-modern-app-here (I am exaggerating the idea but you get the point)!

    Of course a working textile to html would also do the job.

  • 0
    Patrick Wolf

    Hey Maxim, thanks for your helpful comment. I created a public feature request here to fully implement textile or switch to markdown. Feel to comment and vote there and then lets hope we get it some day :)

  • 0
Please sign in to leave a comment.