Quickstart for writing Markdown on GitHub

What this covers

GitHub's Quickstart for writing on GitHub teaches advanced formatting by creating or editing a profile README. You write Markdown (plus a few supported HTML tags) in README.md, Preview in the editor, and commit. If you are new to Markdown, start with Basic writing and formatting syntax or the Communicate using Markdown GitHub Skills course.

If you already have a profile README, add features to it, or practice in a gist named something like about-me.md (Creating gists).

flowchart LR
    Scaffold[Scaffold Profile README] --> Media[Add dark and light mode picture tags]
    Media --> Tables[Format data tables with alignment]
    Tables --> Tasks[Insert tasklists for tracking]
    Tasks --> Preview[Validate rendered output in Preview tab]

Create or open your profile README

Your profile README appears at the top of your GitHub profile.

New profile README:

1. Create a repository with the same name as your GitHub username, and initialize it with a README.md file. See Managing your profile README.
2. Edit README.md and delete the starter template text (the block that begins ### Hi there).

Existing profile README:

1. In the upper-right corner of any page, click your profile picture, then click Your profile.
2. Click the pencil next to your profile README to edit.

Add a responsive image

Include a banner that swaps for light vs dark mode with a `` element and prefers-color-scheme.

1. Paste this markup into README.md:

      <img alt="YOUR-ALT-TEXT">

2. Replace the placeholders with image URLs (or use GitHub's example URLs below).
3. Set YOUR-ALT-TEXT to a short description for screen readers.
4. Click the Preview tab to confirm the image renders.

Example:

      <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">

Theme details: Managing your theme settings. Image Markdown: Basic writing and formatting syntax.

Add an About me table

1. Return to the Edit file tab.
2. Two lines below the picture markup, add a heading and short intro:

## About meHi, I'm Mona. You might recognize me as GitHub's mascot.

3. Two lines below that, insert a ranking table. Right-align a numeric column with --: under the header:

| Rank | THING-TO-RANK ||-----:|---------------||     1|               ||     2|               ||     3|               |

4. Replace THING-TO-RANK (for example Languages or Hobbies) and fill the rows.
5. Click Preview.

Filled example:

## About meHi, I'm Mona. You might recognize me as GitHub's mascot.| Rank | Languages ||-----:|-----------||     1| JavaScript||     2| Python    ||     3| SQL       |

More on tables: Organizing information with tables.

Wrap the table in a collapsed section

Keep the README tidy with <details> / <summary>:

<details><summary>My top THINGS-TO-RANK</summary>YOUR TABLE</details>

Replace THINGS-TO-RANK with the same label you used in the table. Optionally start expanded:

<details>

Preview again after wrapping.

Add a horizontal rule and quote

1. Below the details block, type three or more dashes for a rule:

---

2. Add a blockquote:

> QUOTE

Example:

---> If we pull together and commit ourselves, then we can push through anything.- Mona the Octocat

3. Click Preview.

Add a hidden HTML comment

Two lines below ## About me, insert a comment that stays hidden in the rendered README:

Preview to confirm it does not appear in the output.

Save your work

When you are happy with the Preview, click Commit changes.

• Commit to main to publish on your profile immediately.
• Or choose Create a new branch for this commit and start a pull request if you want to stage changes first.

What you will practice

Next steps

• Creating diagrams
• Creating and highlighting code blocks
• Communicating on GitHub