Our engineering and security teams do some incredible work. Let’s take a look at how we use GitHub to be more productive, build collaboratively, and shift security left.

Learn more

Explore how to write, build, and deploy enterprise software at scale.

Automation

Automating your way to faster and more secure ships.

CI/CD

Guides on continuous integration and delivery.

Collaboration

Tips, tools, and tricks to improve developer collaboration.

DevOps

DevOps resources for enterprise engineering teams.

DevSecOps

How to integrate security into the SDLC.

Governance & compliance

Ensuring your builds stay clean.

!Image 9 GitHub recognized as a Leader in the Gartner® Magic Quadrant™ for AI Code Assistants

Learn why Gartner positioned GitHub as a Leader for the second year in a row.

Learn more

Keep up with what’s new and notable from inside GitHub.

Company news

An inside look at news and product updates from GitHub.

Product

The latest on GitHub’s platform, products, and tools.

Octoverse

Insights into the state of open source on GitHub.

Policy

The latest policy and regulatory changes in software.

Research

Data-driven insights around the developer ecosystem.

The library

Older news and updates from GitHub.

!Image 10 Unlocking the power of unstructured data with RAG

Learn how to use retrieval-augmented generation (RAG) to capture more insights.

Learn more

Everything open source on GitHub.

The latest Git updates.

Maintainers

Spotlighting open source maintainers.

Social impact

How open source is driving positive change.

Gaming

Explore open source games on GitHub.

!Image 11 An introduction to innersource

Organizations worldwide are incorporating open source methodologies into the way they build and ship their own software.

Learn more

Stay up to date on everything security.

Application security

Application security, explained.

Supply chain security

Demystifying supply chain security.

Vulnerability research

Updates from the GitHub Security Lab.

Web application security

Helpful tips on securing web applications.

!Image 12 The enterprise guide to AI-powered DevSecOps

Learn about core challenges in DevSecOps, and how you can start addressing them with AI and automation.

Learn more

GitHub for Beginners: Getting started with Markdown

Discover how to format and edit your comments and posts using Markdown.

[Kedasha Kerr](https://github.blog/author/ladykerr/ "Posts by Kedasha Kerr")·@ladykerr

April 28, 2026

| 6 minutes

Share:
[](https://x.com/share?text=GitHub%20for%20Beginners%3A%20Getting%20started%20with%20Markdown&url=https%3A%2F%2Fgithub.blog%2Fdeveloper-skills%2Fgithub%2Fgithub-for-beginners-getting-started-with-markdown%2F)
[](https://www.facebook.com/sharer/sharer.php?t=GitHub%20for%20Beginners%3A%20Getting%20started%20with%20Markdown&u=https%3A%2F%2Fgithub.blog%2Fdeveloper-skills%2Fgithub%2Fgithub-for-beginners-getting-started-with-markdown%2F)
[](https://www.linkedin.com/shareArticle?title=GitHub%20for%20Beginners%3A%20Getting%20started%20with%20Markdown&url=https%3A%2F%2Fgithub.blog%2Fdeveloper-skills%2Fgithub%2Fgithub-for-beginners-getting-started-with-markdown%2F)

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.

1. Navigate to a repository you own on github.com. 2. Make sure you are on the **Code** tab of your repository. 3. Click **Add file** near the top of the window and select **Create new file** from the pull-down menu. 4. In the box at the top of the editor, name your file. Make sure the filename ends in `.md` (e.g., `markdownTestFile.md`). 5. Select the **Edit** button. 6. 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.

Additional resources

Check out the GitHub docs for a cheat sheet on formatting Markdown.

You can also start practicing your Markdown skills today by visiting the communicate-using-markdown skills repository. You’ll learn how to use Markdown to add lists, images, and links in a GitHub comment or text file.

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.

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.

![Mona](https://avatars.githubusercontent.com/u/92997159?v=4)

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 Kerr](https://github.blog/author/ladykerr/)

@ladykerr

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.

More on [GitHub for beginners](https://github.blog/tag/github-for-beginners/)

[GitHub for Beginners: Getting started with GitHub Pages](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-pages/)

Learn how to create a free website for any repository on GitHub Pages.

[Kedasha Kerr](https://github.blog/author/ladykerr/ "Posts by Kedasha Kerr")

[GitHub for Beginners: Getting started with GitHub security](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-security/)

Learn how to secure your projects and keep them safe with GitHub Advanced Security.

[Kedasha Kerr](https://github.blog/author/ladykerr/ "Posts by Kedasha Kerr")

Developer skills

[GitHub for Beginners: Getting started with GitHub Pages](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-pages/)

Learn how to create a free website for any repository on GitHub Pages.

[Kedasha Kerr](https://github.blog/author/ladykerr/ "Posts by Kedasha Kerr")

Developer skills

[GitHub for Beginners: Getting started with GitHub security](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-security/)

Learn how to secure your projects and keep them safe with GitHub Advanced Security.

[Kedasha Kerr](https://github.blog/author/ladykerr/ "Posts by Kedasha Kerr")

AI & ML

[Building AI-powered GitHub issue triage with the Copilot SDK](https://github.blog/ai-and-ml/github-copilot/building-ai-powered-github-issue-triage-with-the-copilot-sdk/)

Learn how to integrate the Copilot SDK into a React Native app to generate AI-powered issue summaries, with production patterns for graceful degradation and caching.

[Andrea Griffiths](https://github.blog/author/andreagriffiths11/ "Posts by Andrea Griffiths")

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

We do newsletters, too

Discover tips, technical guides, and best practices in our biweekly newsletter just for devs.

Your email address

*Your email address

[x] Yes please, I’d like GitHub and affiliates to use my information for personalized communications, targeted advertising and campaign effectiveness. See the GitHub Privacy Statement for more details.

Site-wide Links

[](https://github.com/)

Product

Platform

Support

Company

Terms
Privacy
Manage Cookies
Do not share my personal information

!Image 22×

GitHub for Beginners: Getting started with Markdown

GitHub for Beginners: Getting started with Markdown - The GitHub Blog

Categories

GitHub for Beginners: Getting started with Markdown

What is Markdown and why is it important?

Where can I use Markdown?

Basic syntax

Lists

Additional resources

Code

Clone the repository

Install dependencies

Start the development server

Links and images

What’s next?

Tags:

Written by

[Kedasha Kerr](https://github.blog/author/ladykerr/)

Table of Contents

More on [GitHub for beginners](https://github.blog/tag/github-for-beginners/)

[GitHub for Beginners: Getting started with GitHub Pages](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-pages/)

[GitHub for Beginners: Getting started with GitHub security](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-security/)

Related posts

[GitHub for Beginners: Getting started with GitHub Pages](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-pages/)

[GitHub for Beginners: Getting started with GitHub security](https://github.blog/developer-skills/github/github-for-beginners-getting-started-with-github-security/)

[Building AI-powered GitHub issue triage with the Copilot SDK](https://github.blog/ai-and-ml/github-copilot/building-ai-powered-github-issue-triage-with-the-copilot-sdk/)

Explore more from GitHub

Docs

GitHub

Customer stories

The GitHub Podcast

We do newsletters, too

Site-wide Links

Product

Platform

Support

Company