Markdown: The Formatting Language Behind GitHub

Markdown is a lightweight markup language for formatting plain text, and it is used throughout GitHub for README files, issues, pull requests, discussions, and wikis. It lets you create clear, consistent documentation without learning a full page-layout system. The syntax also carries over to many other tools — modern note-taking apps, blogs, and documentation platforms all support it — so it is a useful skill beyond your GitHub workflow.

Where Markdown Shows Up

The file you will most often write in Markdown is your repository README. But you will also use it whenever you create or comment on issues and pull requests, as well as in wikis and discussion threads. On any of these surfaces, Markdown is what turns your plain text into structured, readable content.

Testing the Syntax

The easiest way to practice is to create a test file in a repository you own. You can see rendered output without saving anything:

  1. Open a repository on github.com and make sure you are on the Code tab.
  2. Click Add file, then select Create new file.
  3. Name the file with a .md extension, such as markdownTestFile.md.
  4. Click Edit and type Markdown into the editor.
  5. Select Preview to see how your text will render, then use Edit again to keep experimenting.

You do not need to commit the file unless you want to keep it.

Headings and Emphasis

Headings are created by adding pound signs (#) at the start of a line. One # is a top-level header; each additional # creates a subheader.

# GitHub for Beginners 

 

## Basic Markdown syntax 

 

### Headers

To emphasize text, you can use bold and italics, created with either asterisks (*) or underscores (_). You must pair the symbols correctly: a single character around text makes it italic, double characters make it bold, and triple characters make it both. This works for individual words or entire strings.

Here is some *italic text* 

Here is some **bold text** 

___Here is both bold and italic text 

Over multiple lines___

Block quotes are made by putting a greater-than symbol (>) as the first character of a line. For multi-line quotes, add the symbol at the start of every line.

> No design skills required. 

> 

> No overthinking allowed. 
> 

> Just ship your work.

Formatting Lists

Ordered lists are written by numbering items with periods, such as 1. and 2.. You do not need to keep the numbers sequential — Markdown interpreters will render the list in order regardless of the exact numbers you type. This means you can insert an item later without renumbering the whole list.

1. Click the "Use this template” button at the top of this repo. 

1. Name your new repository (e.g., my-portfolio). 

1. Clone your new repo and start customizing!

Unordered lists start each line with a hyphen (-), asterisk (*), or plus sign (+).

* Click the "Use this template” button at the top of this repo. 

* Name your new repository (e.g., my-portfolio). 

* Clone your new repo and start customizing!

For nested lists, indent four spaces to start a sublist. This works with both ordered and unordered items. When you finish, press Enter twice to return to regular paragraph text.

1. Click the "Use this template” button. 

    - Located at the top of the repo. 

    - This will create a new repository using this template. 

1. Name your new repository. 

    - e.g., my-portfolio 

    - This can be created under your personal GitHub account. 

1. Clone your new repo and start customizing!

Writing Code Snippets

Inline code is denoted by surrounding text with a single backtick (`).

`git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git`

For code spanning multiple lines, use a code block delimited by three backticks at the start and end. Everything between them, including newlines and spaces, is rendered as code, and most Markdown interpreters add syntax highlighting.

```bash 

# Clone the repository 

git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git 

cd YOUR_REPO_NAME 

 

# Install dependencies 

npm install 

 

# Start the development server 

npm run dev 

```

Links follow the pattern of brackets followed immediately by parentheses: the display text goes in [] and the URL in (), with no space between them. Images work identically, but with an exclamation point (!) prepended, which makes them suitable for screenshots, diagrams, or logos in a README.

Open [your local host](http://localhost:3000) to see your portfolio. 
![Mona](https://avatars.githubusercontent.com/u/92997159?v=4)

On GitHub itself, you can simplify image insertion by dragging and dropping an image directly into an issue or pull request — GitHub generates the necessary Markdown for you.

Next Steps

With these basics, you can write clean and readable documentation across your repositories. Start with these techniques and apply them to your next README, issue, or project note.

For further reading, GitHub’s documentation covers basic formatting syntax, creating and highlighting code blocks, and a quickstart for writing on GitHub.