Skip to content
Source
Sign inSign up

Write comments

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

The editor on the Split tab: the formatting toolbar, the Markdown text on the left and its live preview on the right

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.

ButtonWhat it does
HeadingMakes the line a heading
Bold, ItalicMakes the text bold or italic
QuoteMakes the lines a quote
CodeMakes the text code
LinkMakes the text a link
Bulleted list, Numbered list, Task listMakes 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.

  1. Type @. A list of the people of the repository opens.
  2. 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.

The editor in the dark theme after typing @al: a list under the text suggests the person AlemTuzlak

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

  1. Write a code block with the language mermaid:

    ```mermaid
    flowchart LR
      A[Push] --> B[CI] --> C[Deploy]
    ```
  2. 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 mermaid code blocks show as diagrams.
  • The people that you mention get a notification, #12 links to the issue, and acme/app#12 links to the issue of that repository.

To fix a comment after you post it, see Edit the title, the description and comments.