Contents of a Story



Stories are the standard unit of work in Shortcut. Stories are where collaboration and documentation for said unit of work happens.

The contents of a stories entails user-generated content that can be edited or removed by anyone in the workspace. This article will break down this content by their respective elements.

Story Basics

Story Title


Click the Story Title to open the title box. Once edited, hit enter or click outside of the title box to save the new title.

There is a 512 character limit to the content of a Story title.

Story Description

Click the editdescriptionbutton.png button to edit description. You can also shift+click anywhere in the description to start editing.

There is no character limit to the content of the description. It can be as long or short as you need it to be. Story descriptions support both Markdown and HTML.

Story Tasks

Tasks are steps you may need to carry out in order to complete a story. They are entirely optional but can be helpful in breaking down a large effort. 

When you complete a task, you can click the checkbox and it will cross it out as completed.


Completion of Tasks doesn't indicate any amount of progress towards the completion of a Story; Shortcut tracks Story progress based on its forward movement through the workflow States.


Assign a task to someone

While a Story Owner is responsible for the completion of the Story, many team members may be needed to help with individual jobs within a Story. You can assign tasks to people by using the Task assignment menu after the Task is created and saved.




If a Task is assigned to you, you’ll see it on your Dashboard until that task is marked complete.


Convert a task into a Story

If a task appears too large, or if it the list of tasks grows overwhelming, you may want to turn a task into a Story. You can do this easily in Shortcut by clicking the Convert to Story button.


The task title becomes the title of a new Story, and any task owners become owners of the new Story.

Story Relationships

Stories in Shortcut can be related to each other in a number of ways and within the Story dialog. Once you indicate this relationship in one Story, it will automatically appear in both.

Story Relationships

To add one, click Relationships under Add to Story and select the appropriate relation type: 

  • Relates to means there is some relationship between the two Stories.  
  • Blocks means Story A needs to be completed before Story B can start. Story B will be marked Is blocked by Story A. When Story A is completed, these properties will be removed from both Stories Cards.
  • Duplicates is to be used when an identical or very similar Story already exists in the system. While we expect the duplicate Story to be archived, it will continue to contain the Is duplicated by relationship indicating to all who come across it that it is not the original Story. 

To add a Doc Relationship, use Docs Tab and search for the Doc.

Doc Relationship


To end the relationship, select the three dots to the right of the relationship and select Remove Relationship.


Story Comments


Discussion about a Story can take place in the Comments & Attachments section of the Story dialog. The comments field supports text, markdown, emoji, files, links, and code snippets. Clicking into the comment text area will provide you with numerous helpers. 

The system will share a message informing you of this and the Story card will have a pencil icon indicating that the Story has unsaved changes.


Mention a user in a comment

You can reference or call attention to a team member in a comment by typing "@" and then typing or selecting the person's username in the dropdown. They will receive an email notification (and Slack DM as well, if enabled).

Story Comment example

Add an image to a Story Comment

Upload File Limits

The web app has a 50MB file upload limit. 

An image attachment is restricted in three ways:

  • Images attached to a story are scaled down to at most 360 pixels wide and 240 pixels high.

  • Clicking on an image to display it hi-res in a lightbox causes it to be scaled to the size of the browser window. (So very tall and skinny images can become difficult to see)

You can add images to the comments field in three ways:

1) Click the image icon to select a file to upload

Attach files

2) Drag and drop the image from your computer into the comment area. Hold the Shift key to bring up the optional image cropper.

3) Copy/paste the image from your clipboard (NOTE: Copy/paste is currently only supported in Chrome. It will be added to other browsers when it becomes available in the spec).

Animated GIFs will become static GIFS when copy-pasted.

Link users to a Story comment

If you want to reference a comment or file from another Story (or even the same Story), you can get the comment's unique URL by hovering over the comment's date and time, right clicking, and copying the link location.




Emoji reaction to Story Comment


In addition to using emojis in the text of a comment, you can also react directly to a comment. 

To react to a comment using an emoji:

  1. Open the Story containing the comment.
  2. Find the comment and move your mouse over the comment body.
  3. Click on the smiley face icon that appears below the comment text (on hover the button will say Add Reaction).
  4. Scroll or search to find the emoji you want, and then click on the emoji to add it to the comment.

To remove your reaction from a comment, click the emoji again.

Note: Emoji reaction updates won't trigger notifications or be included in the Activity Feed.

Pinning Stories

You can pin Stories to the bottom of the UI for easy access which allows quick retrieval without needing to open multiple taps. Now you can multi-task with ease!

Story Pinning


Story Activity



The Story Activity is located at the bottom of the story card and shows you who created the story and when and by whom the story state has changed.

At the top of the Story Activity section, we show 'Important Changes Only' by default. This setting will show important changes such as pull requests opened or merge requests linked to this story; when the story is moved from one state to another; or when tasks are completed.

The second setting is called 'Everything'. As the term implies, this will show all metadata changes to the story, such as changes to the title or description; when labels have been added/removed; owners added/removed; followers added/removed; due date changed, etc.

Difference Checker


Shortcut records the text for the title and description. When changes are made to the story, we show the text difference between the two versions. This can be seen by setting the Story Activity to 'Everything' and check for the Diff button next to a title or description change.





Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request