Issues and pull requests / Issues
Write comments and descriptions
A good comment has headings, lists, code, screenshots and links to issues, and you want to see the result before you post. Each comment box and description box has a Markdown editor: a toolbar, a live preview, images and suggestions for people and issues.
4 min read

1. Format the text
Select the text, then click a button in the toolbar. With no text selected, the button adds the Markdown at the cursor.
| Button | What it does |
|---|---|
| Heading | Makes the line a heading |
| Bold, Italic | Makes the text bold or italic |
| Quote | Makes the lines a quote |
| Code | Makes the text code |
| Link | Makes the text a link |
| Bulleted list, Numbered list, Task list | Makes the lines a list |
Keyboard shortcuts (Cmd on a Mac):
Ctrl+B: bold.Ctrl+I: italic.Ctrl+E: code.Ctrl+K: link.
2. See the result while you type
The editor has three tabs:
- Write: only the text.
- Split: the text, with the live preview beside it.
- Preview: only the result.
The editor opens on Write. To see the preview while you type, click Split.
Note
On a narrow screen, there is no Split tab. Use Write and Preview.
3. Add a screenshot or a video
Paste the file into the text, drop it on the text, or click Attach files under the text. The editor uploads the file and puts it in your text.
Who can attach, the file types and the limits are in Add images and videos to issues and comments.
4. Mention a person or link an issue
- Type
@. A list of the people of the repository opens. - Type a part of the name, then pick the person.
Type # to pick an issue or a pull request in the same way. The editor puts #<number> in the text.
- Type a number, for example
#12, to find item 12 first, then the items whose number starts with 12. Closed items are in the list too. - Type a word to find the items with that word in the title or the description.
In a description or a comment, #12 links to issue or pull request 12 of the repository. To link an item of another repository, write its name before the number: acme/app#12. Text in code (`#12` or a code block) does not become a link.

Note
On an item that syncs with GitHub, the editor warns you when your text links to this site, or names an item that exists only here. GitHub shows the text as you wrote it. See Sync with GitHub.
5. Draw a diagram
Write a code block with the language
mermaid:flowchart LR A[Push] --> B[CI] --> C[Deploy]Click Preview to see the diagram.
The diagram shows in every place that shows Markdown: descriptions, comments, intent summaries, README files and other Markdown files. The source of the diagram is in Diagram source under it.
- Until you write the closing
```, the preview shows Drawing the diagram… in the place of the diagram. - When the diagram cannot be drawn, the code block stays, with a note that tells you why.
Done
- Your comment has headings, lists and code, and you saw the result before you posted it.
- Your screenshots and videos show in the comment.
- Your
mermaidcode blocks show as diagrams. - The people that you mention get a notification,
#12links to the issue, andacme/app#12links to the issue of that repository.
To fix a comment after you post it, see Edit the title, the description and comments.