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.

Examples

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

Strikethrough

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

Links

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

Markdown Output
[Example Site](http://example.com) Example Site

Images

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

Code

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

Block-level styling

Paragraphs

First paragraph

Second paragraph
with manual line-breaks

Third paragraph

Headings

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

Subtitle
--------

Lists

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
checkbox

Blockquotes

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

Tables

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:
Keys|Values
-|-
id|1234  
code|Yoyo  

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
```javascript
['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…
Bold
Italics _Italics_ Renders as…
Italics
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…
® ™ ©

Links

Type Syntax Description
Simple link to a web page https://shotgunsoftware.com is a great site! Renders as…
https://shotgunsoftware.com is a great site!

Generally supports:
  • HTTP and HTTPS (with or without port numbers)
  • FTP
  • DMX
  • GOPHER
Relative link "This site's contact link":/contact Renders as…
This site’s contact link
Link with display text "Shotgun":http://www.shotgunsoftware.com/
"Local link relative to base url":/support/contact
 
Email link support@shotgunsoftware.com should be contacted Renders as…
support@shotgunsoftware.com 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...
     nil
else
     @reflect.klass
end
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.

Images

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:
/storage/production/files/000/0004/demo-file.png
URL-linked images !https://support.shotgunsoftware.com/hc/en-us/article_attachments/114094096954/11_play_media.png! 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.
Follow

12 Comments

  • 0
    Avatar
    Armando Ricalde

    Relatively linked images (uploaded to Shotgun)

    !/files/0000/0000/0041/Shotgun_Icon_2.jpg!

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

  • 0
    Avatar
    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
    . **

    !/file_serve/attachment/25!

     

    **2. This also works

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

    !https://demo.shotgunstudio.com/storage/production/files/0000/0000/0025/demo_file.png!

     

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

     !/storage/production/files/0000/0000/0025/demo_file.png!

     

  • 0
    Avatar
    Marijn Eken

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

  • 0
    Avatar
    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
    Avatar
    Jean-Paul LeDoux

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

  • 0
    Avatar
    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
    Avatar
    François TARLIER

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

  • 0
    Avatar
    Maxim Doucet

    For tickets, the following syntax does work for me:

    #999

    Where "999" is the number of your ticket.

  • 0
    Avatar
    Patrick Wolf

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

    "Google": http://www.google.com/ 

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

    Are links still supported?

    Thanks

  • 0
    Avatar
    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
    Avatar
    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
    Avatar
Please sign in to leave a comment.