Introduction to Markdown and README files

Aims and Objectives

Markdown is a lightweight markup language that you can use to add formatting elements to plain-text text documents. GitHub uses markdown for a variety of applications across repositories and projects, including for README files, issues, discussions, commit messages, and comments. This Introduction to Markdown skills session will use a a mixture of directed, interactive lessons and GitHub Skills to provide NOAA Fisheries staff with a foundation in markdown language formatting and editing.

Prerequisites: What do I need before this workshop to follow along on my own?

This stand-alone skills session is meant for those with a basic understanding of Git and GitHub. Check out our Introduction to Git and GitHub lessons if you are new to Git and GitHub or need a refresher.

What is Markdown?

Using Markdown in GitHub - Tutorial

Important

GitHub Skills are systematically being updated to an issue-based workflow from the legacy README-based workflow. The following tutorial follows the updated issue-based workflow. If you began this exercise before 5-30-2025, your skills repository will look different from the current skills repository template. If this is the case, click here for the legacy README-based tutorial.

GitHub Skills: Communicate using markdown

We’ll be using the Communicate Using Markdown Skills Tutorial to get some practice with markdown in GitHub. Follow along with the tutorial using your own GitHub account.

Step 1: Copy the exercise

Open the GitHub Skills link, and make sure you are logged into GitHub. Use the “Copy Exercise” button to make a new repository on your account:

When you open up the “Copy Exercise” link, you will be presented with the “Create a new repository” interface. Keep all of the defaults, and click the green “Create repository” button:

GitHub Skills tutorials use GitHub Actions in the background.

These actions use “minutes”, which are limited in a private repository, but unlimited in a public one. We suggest keeping your GitHub Skills tutorial repositories public to avoid any minutes limitations.

You’ll notice that most steps in a GitHub Skills tutorial feature a message to wait about 20 seconds for the exercise to update.

GitHub Actions can take a little bit of time to run, so waiting this requisite time is important! Refresh the instructions after 20 seconds to make sure everything updates properly.

Step 2: Start the exercise

After waiting the suggested 20 seconds, refresh the repository, and click the “Go to Exercise” button in the README

Tip

I suggest moving the instructions tab into another window so you can work side-by-side with the instructions to limit switching back and forth between tabs.

Step 3: Follow the exercise

Create a markdown file in a new branch

In this exercise, we will be using markdown to create an example “blog” page. The content provided in the exercise is just an example; we can give a more personal touch to our own content.

Tip

During this tutorial, GitHub Skills will provide code blocks that you can copy directly to your clipboard to paste into the body of your Markdown document. But this defeats the purpose of getting practice with Markdown and building that muscle memory! Go ahead and type in your own content (don’t worry, it doesn’t have to match the example content perfectly)

1. On the Code tab of your repository, click the dropdown menu where it says “main”
   
2. In the “Find or create a branch” box, type start-blog and select “Create branch start-blog from main”
   
3. Create a new file by clicking the “Add file” button in your new branch (note this may look like a + symbol if you’re working in a condensed side-by-side view) and click “Create new file”
   
4. Along the top of the dialogue box, name your file day-1.md
   
5. In your new file, create a level one heading to give the page a title
   
6. Add a couple level 2 headings for the names of each of the blog posts
   
7. Click the Preview tab in the top left of the dialogue box to view your rendered content
   
8. Click the “Commit changes” button in the top right and commit the changes directly to the start-blog branch
   

Make a list

1. Re-open the day-1.md file and click “Edit this file”
   
2. In the ## Morning Planning section, add a list of each type: unordered, ordered, and task
   

Note

GitHub skills only asks for a task list, but we want you to have practice with all list types; adding the other types will not mess up the GitHub Skills workflow, so go ahead and practice adding all three types!

3. Preview your content in the preview tab
   
4. Commit your changes directly to the start-blog branch
   

Add a code sample

1. After this commit, the day-1.md file should still be open. Click the “Edit this content” button to go back into editing mode
   
2. In the “Review” section, add a code chunk using the three backtick notation (it’s okay to use a different example than the one provided by GitHub Skills)
   
3. Preview your content
   
4. Commit your changes to the start-blog branch
   

Add an image

1. Open our day-1.md file in edit mode
   
2. Insert an image below the the “Morning Planning” level 2 heading. To make things a little more interesting, let’s use the Scubatocat image located at https://octodex.github.com/images/scubatocat.png
   
3. Preview your Markdown file
   
4. Go back to the Edit tab and replace the image with an HTML version that changes the size and position
   
5. Preview your updated image, and Commit changes to start-blog

Add some formatted text (off-script

Before we finish up our tutorial, let’s add some formatted text. The GitHub Skills lesson does not mention anything about this, but it’s an important part of markdown that you should get some practice with!

1. Edit your day-1.md file one more time
   
2. Under the Daily Learning heading, add some bolded, italicized, and in-line code text
   
3. Preview your file, then commit your changes
   

Finish work: Merge your blog post

This step doesn’t have anything to do with markdown, but it’s good practice for working with Pull Requests from a branch!

1. Select the “Pull requests” tab in the top navigation bar
   
2. Click the “Compare & pull request” button for start-blog
   
3. Click the “Create pull request button”
   
4. Merge your pull request and confirm the merge
   
   

What about README files?

All of the things we did in this tutorial can be done in a README file! To illustrate this, we can copy the contents of our day-1.md file over to our README.md file in our Skills repository:

1. Navigate to the Code tab in the top navigation menu
   
2. Select day-1.md and switch to the Code view
   
3. Click the “Copy raw file” button at the top of the dialogue box (looks like two overlapping squares)
   
4. Navigate back to the Code tab, and edit the README file by clicking the “Edit file” button on the README
   
5. Replace the text in the dialogue box with the copied text from the day-1.md file
   
6. Commit your changes
   
7. Navigate back to the Code tab (this should bring you to the home page of our repository, and scroll down to see your markdown-formatted README file!