GitLab Markdown Basics

Markdown is a simple way to format text with plain keyboard symbols. GitLab reads Markdown in issues, merge requests, comments, wikis, and README files. A pound sign makes a heading, and two asterisks make bold text. Nothing needs a mouse or a toolbar.

Think of Markdown as shorthand notes. You type quick marks, and GitLab turns them into a neat, finished page.

From Symbols to Formatted Text

  YOU TYPE                         GITLAB SHOWS
  ─────────────────────────        ─────────────────────────
  ## Project Goals                 Project Goals  (large heading)
  This is **important**            This is important  (bold)
  - Write code                     • Write code
  - Test code                      • Test code

Headings and Text Styles

# Heading level 1
## Heading level 2
### Heading level 3

**bold text**
_italic text_
~~crossed out text~~
`inline code`

Leave a blank line between paragraphs. A single line break inside a paragraph stays in the same paragraph.

Lists

Bullet List

- Apples
- Bananas
  - Small bananas
  - Large bananas

Indent two spaces to create a sub-item.

Numbered List

1. Clone the project
2. Create a branch
3. Open a merge request

Task List

- [x] Write the code
- [ ] Add tests
- [ ] Update the guide

GitLab renders clickable checkboxes and shows a progress count such as "1 of 3 tasks completed" on the issue list.

Links and Images

[GitLab home](https://gitlab.com)
![Diagram of the login flow](images/login-flow.png)

The text in square brackets becomes the clickable label. For an image, the bracket text becomes the alternative text that screen readers announce, so describe the picture in a short phrase.

Tables

| Name  | Role      | Team     |
|-------|-----------|----------|
| Riya  | Developer | Frontend |
| Arjun | Tester    | Quality  |

Pipes separate columns. The row of dashes under the header is required.

Code Blocks

Three backticks start and end a block. Add a language name after the opening backticks to color the code.

```python
def greet(name):
    return "Hello " + name
```

GitLab Reference Shortcuts

GitLab Flavored Markdown adds shortcuts that link to project items.

Type	Result
#42	Link to issue 42
!7	Link to merge request 7
@riya	Mention the user riya and send a notification
%"Version 2.0"	Link to a milestone
~bug	Show the label named bug
a1b2c3d	Link to a commit by its short identifier

Diagrams with Mermaid

GitLab draws diagrams from text. Place the diagram code inside a code block that uses the language name mermaid.

```mermaid
graph LR
  A[Write code] --> B[Push]
  B --> C[Pipeline]
  C --> D[Deploy]
```

The block above shows a four-step flow as a drawn chart. Teams use Mermaid for flowcharts, sequence diagrams, and timelines inside wikis and issues.

Collapsible Sections

Long logs and details fit inside a section that readers open on demand.

<details>
<summary>Click to view the full error log</summary>

Error: connection timed out after 30 seconds

</details>

Emoji

Type a colon, an emoji name, and a closing colon. The text :tada: shows a party popper, and :warning: shows a warning sign. Use emoji sparingly so that meaning stays clear.

Write a Strong README

# Project Name
One sentence that explains what the project does.

## Install
Steps to set up the project.

## Usage
A short example that new users can copy.

## Contribute
How to report bugs and submit changes.

Preview Before Posting

Every text box in GitLab has a Preview tab beside Write. Select Preview to check headings, links, and tables before you save.

Writing Habits

• Use one heading level at a time and avoid skipping levels.
• Keep paragraphs short.
• Describe images with meaningful alternative text.
• Name links with clear labels rather than the words "click here".
• Use task lists to track small checklists inside issues.