Docs allow for free form documentation, ideation, and collaboration in an easy-to-use document editor. You can use Docs to house any internal documentation that you would like to share or reference anywhere in Shortcut.
We’re Updating Docs
We’re rolling out an updated Docs experience that unlocks a range of new editing and collaboration features, many of which are described below. As these changes roll out, you may notice differences in how your Docs look and behave. If you run into any issues with your Doc’s content, reach out to us at support@shortcut.com and include the Doc’s URL so we can take a look.
Editor
- Type ”/” anywhere in a Doc to open the slash menu. Use it to quickly insert content, such as headings, lists, tables, and code blocks, right where your cursor is, or to search for and link a Story, Epic, Iteration, Objective, or Doc. Linked entities will appear in the Doc Relationships sidebar.
- Relationships are a two-way street; the link is shown from both the Doc and the entity being linked. Note, a URL link to a Story, Epic, Doc, Iteration or Objective can also be pasted directly into the Doc.
- Tip: For a quick view of the information within each respective Shortcut entity, such as progress and other important details, simply hover over the linked Story, Epic, Iteration, Objective, or Doc.
- Insert and customize content blocks from the Add/Edit icon or the slash menu, including headings (H1-H3), bulleted, numbered, or to-do lists, block quotes, horizontal lines, code blocks, tables, and images or videos. Videos can be embedded via URL. To create a threaded list, press Enter for a new line and Tab to create a sublist.
- Table of Contents: Add a Table of Contents block to generate a linked overview of your Doc’s headings, letting readers jump straight to any section. It stays up to date as you add, remove, or edit headings.
- Mermaid diagrams: Create diagrams such as flowcharts, sequence diagrams, and more by writing Mermaid syntax, which renders as a visual diagram right in your Doc.
- Highlight any text to access formatting options including bold, italic, underline, strikethrough, code, a range of text and highlight colors, hyperlinks, and comments. You can also create Stories, Epics, Iterations, and Objectives directly from highlighted text without leaving the Doc. The highlighted text becomes the new entity’s title.
- Markdown: Paste Markdown directly into a Doc and it’s converted to formatted content automatically. You can also use Markdown shortcuts as you type. For example, type
#for a heading,-for a bulleted list, or>for a block quote. - Document outline: Get a high-level view of your Doc’s structure and jump to any section using the outline, which is generated automatically from the headings in your Doc and updates as those headings change.
Comments & Suggestions
Comments
Leave feedback on any highlighted text, and mention a teammate in a comment to loop them in. Reply within a thread to keep the conversation together, so back-and-forth stays attached to the text it’s about. Open the Comments panel using the icon in the top right of the Doc to see every thread in one place, where you can review feedback and jump to it anywhere in the Doc.
Resolved Comments
Once a thread’s feedback has been addressed, resolve it to clear it from the active view and reduce clutter. Resolved comments aren’t deleted, and they remain accessible whenever you need to revisit the conversation.
Suggestion Mode
Suggestion Mode lets collaborators propose edits without changing the Doc directly. Changes are color coded: additions in green, deletions in red, and formatting changes in blue. Any editor can enable Suggestion Mode from the dropdown in the top right corner, and suggestions can be reviewed, then accepted or rejected, from the Suggestions panel. By default, Docs open in Editing mode.
Organization
Docs Menu
The menu on the left side of the page lets you navigate between Recent, My Docs, All Docs, Following, Templates, Favorites, and Collections.
Templates
Templates are pre-made structured guides to enable your team to get started quickly. Note, while the template section itself can not be modified, the Templates can be duplicated, edited, and saved under a Collection as needed.
Collections
Collections are labeled groups for organizing Docs, similar to how an Epic houses Stories. Unlike standard folders, a Doc can belong to multiple Collections at once. For example, a PRD can live in both a PRD Collection and a Product Collection, making it easy to find regardless of who is looking. Collections support Sub-Collections for additional nesting, are visible to everyone in the Workspace, and are sorted alphabetically. Private Docs within a Collection are only visible to users with access to that Doc.
Permissions
Grant Doc Owners with access control by selecting the dropdown at the top right of the page and choosing between Workspace-wide, Shared with specific teammates, or Private (visible only to you).