Welcome back to GitHub for Beginners. We’ve covered a wide range of topics so far this season, including GitHub Issues and Projects, GitHub Actions, security, and GitHub Pages. Now we’re going to teach you everything you need to know to get started with Markdown, the markup language used across GitHub.
Once you learn the basics of how to use Markdown, you’ll develop an essential skill that will transform how you write READMEs as well as how to format issues, pull requests, and your agent instruction files. By the end of this post, you’ll have the knowledge you need to make your projects and contributions easier for others to explore.
As always, if you prefer to watch the video or want to reference it, we have all of our GitHub for Beginners episodes available on YouTube.
What is Markdown and why is it important?
Markdown is a lightweight language for formatting plain text. You can use Markdown syntax, along with some additional HTML tags, to format your writing on GitHub. You can do this in repository READMEs, issue and pull request descriptions, and comments on issues and pull requests.
Markdown gives you the ability to create clear, readable documentation. Having a clean README in your project or a well-formatted issue can make a huge difference when someone lands on your content for the first time.
And one of the best parts is that when you get the syntax down, you’ll find yourself using it in almost every project you work on!
Where can I use Markdown?
The most common place where you’ll encounter Markdown is in your repository’s README file. But you’ll also find yourself using it in issues, pull requests, discussions, and even wikis. Any time you write or communicate on GitHub, Markdown is behind the scenes, helping your text look clean and consistent.
Markdown extends beyond GitHub to modern note-taking apps, blog platforms, and documentation tools. It’s a widely adopted language used across the technical space, so learning how to use it can benefit you beyond just how you interact with GitHub.
Basic syntax
We’re going to start with the common features that you’ll use the most. While we’re going through these, you can try them out to see how they work. The easiest way to do this is by opening a markdown file on your repository.
- Navigate to a repository you own on github.com.
- Make sure you are on the Code tab of your repository.
- Click Add file near the top of the window and select Create new file from the pull-down menu.
- In the box at the top of the editor, name your file. Make sure the filename ends in
.md (e.g., markdownTestFile.md).
- Select the Edit button.
- Enter any Markdown syntax into the editor window.
You can see what the Markdown text you enter will look like by selecting the Preview button; there’s no need to make a commit unless you want to save your test file. Just select the Edit button to go back to editing so you can enter more Markdown text.
Now that you know how to try it out, let’s get started with the syntax. First up are headers. These are your title and section names. You create them by adding pound signs (#), also known as hashtags, in front of your text. One pound sign indicates a header, two will create a subheader, and so on.
# GitHub for Beginners
## Basic Markdown syntax
### Headers
If you want to emphasize your text, you can use bold and italic fonts. You create these by using either asterisks (*) or underscores (_). Either of these symbols work in the same way, you just have to make sure to pair them up appropriately. A single character makes text italic, a double character makes text bold, and a triple character makes it both bold and italic. You can emphasize characters within a string or multiple strings within a line of text.
Here is some *italic text*
Here is some **bold text**
___Here is both bold and italic text
Over multiple lines___
Sometimes you may want to quote important text. To do this, add the greater than (>) symbol as the first character in a line of text. If you would like to quote something that spans multiple lines, you need to add the greater than symbol at the start of each individual line.
> No design skills required.
>
> No overthinking allowed.
>
> Just ship your work.
Lists
Now let’s get into something a little more involved: lists.
Lists are a common way to express your steps and procedures in an ordered and unordered manner. To create an ordered list, number each element in the list (i.e. 1., 2., 3., etc.).
While this can be clear to read, what if you want to add an element between two consecutive numbers? The good news is that you don’t need to renumber the entire list. Markdown interpreters allow you to order your items with any number, and they automatically interpret it as an ordered list from first to last.
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!
For an unordered list, start a line with either a hyphen (-), asterisk (*), or a plus sign (+). Markdown will render any of these characters as the start of an unordered list.
* 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!
If you would like to create nested lists, indent four spaces to start a new indented list. You can do this with both ordered and unordered list items.
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!
When you’re done with your list, hit Enter twice to go back to plain text.
Code
Sometimes you may want to display a snippet of code in your Markdown as an example. This could be for steps in a procedure or as part of your project’s installation process. Many Markdown interpreters render code snippets with formatting and syntax highlighting. You can denote code in Markdown by surrounding it with a backtick (`) character.
`git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git`
If you have code that spans multiple lines, you can use three backtick characters to create a code block. Any characters between these triple backticks, including spaces and new lines, will render as code.
```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 and images
Now let’s learn how to spice up our Markdown files. We’ll start with links. Links allow you to point people to helpful resources, documentation, or other pages in your project. They’re written using brackets ([]) and parentheses (()). Place the text you want to display in the brackets, followed immediately by the URL in parentheses, with no space between the two. This keeps your writing clean and easy to follow.
Open [your local host](http://localhost:3000) to see your portfolio.
Images work in almost the same way, but with one small difference: you need to add an exclamation point (!) at the beginning. This is perfect for adding screenshots, diagrams, or even a project logo to your README.
To make things even easier, on GitHub, you can just drag-and-drop an image into an issue or pull request, and it automatically generates the right Markdown for you.
Whether you’re linking out to a tutorial or showing off a screenshot, links and images help you add that extra bit of personality and clarity to your Markdown.
What’s next?
You now know the basics of Markdown, including what it is, why it matters, where you can use it, and how to start writing it with confidence. With just a few techniques, you can create clean, readable documentation that makes your GitHub projects stand out.
Whether you’re building a README, opening an issue, or writing project notes, Markdown is going to be one of the tools you use the most.
If you want to learn more about Markdown, here are some good places to get started:
Happy coding!
Written by
Kedasha is a Developer Advocate at GitHub where she enjoys sharing the lessons she's learned with the wider developer community. She finds joy in helping others learn about the tech industry and loves sharing her experience as a software developer. Find her online @itsthatladydev.
Explore more from GitHub
Docs
Everything you need to master GitHub, all in one place.
Go to Docs
GitHub
Build what’s next on GitHub, the place for anyone from anywhere to build anything.
Start building
Customer stories
Meet the companies and engineering teams that build with GitHub.
Learn more
The GitHub Podcast
Catch up on the GitHub podcast, a show dedicated to the topics, trends, stories and culture in and around the open source developer community on GitHub.
Listen now
Instagram Engineering
Shopify Engineering