How to Write on GitHub README Formatting, Easy Guide for Beginners!

For formatting plain text, Markdown is a simple language to read and write. You can structure your writing on GitHub using Markdown syntax and a few more HTML tags in places like repository READMEs and comments on pull requests and problems.

By writing or revising a README for your GitHub profile, you’ll gain an understanding of certain advanced formatting capabilities in this tutorial.

Table of Content

Things You Should Know About GitHub README Formatting

  • Start with “Basic writing and formatting syntax” or the Communicate using Markdown GitHub Skills course if you’re new to Markdown.
  • If you already have a profile README, you can follow this tutorial by adding a few features to it or by making a gist using a Markdown file with a name like

Making changes to your profile README

You can tell the community more about yourself by including a README in your profile. Your profile page’s header includes a link to the README file.

  • You can add a profile README if it doesn’t already exist.
  • Create a repository with the same name as your GitHub login and add a file as its initial content. 
  • The template text (starting ### Hello) that is automatically added when you create the file is removed by editing the file.
  • You can change your profile README if you already have one from your profile page.
  • Click your profile picture, then click Your profile, which may be found in the upper-right corner of any GitHub page.
  • An edit icon will appear next to your profile’s README.

Including a suitable image for your audience

On GitHub, you can use photographs in your communications. The responsive image you add here will go at the top of your profile README.

  • You can upload an image that changes based on whether a visitor is using light or dark mode by utilizing the HTML picture> element with the prefers-color-scheme media feature. 
  • The following markup should be copied and pasted into your file.

 <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE">

 <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE">


  • The URLs of the images you’ve chosen should be used in place of the markup’s placeholders. Alternatively, you can copy the URLs from our sample below to test out the capability right away.
  • Change YOUR-DARKMODE-IMAGE to the URL of the image you want to show for users of dark mode.
  • Change YOUR-LIGHTMODE-IMAGE to the URL of an image that will be shown to visitors who are browsing in light mode.
  • If neither of the other images can be matched, for instance, if the visitor is using a browser that does not support the prefers-color-scheme feature, replace YOUR-DEFAULT-IMAGE with the URL of an image to display.
  • Replace YOUR-ALT-TEXT with a description of the image to make it readable for visitors using screen readers.
  • Click the Preview tab to verify that the image has been rendered correctly.
See Also  How to Use GitHub Blooket Hacks, 2 Easy Tips to Follow!

Inserting a table

Markdown tables can be used to arrange the information. Here, you’ll utilize a table to introduce yourself by rating something, such as your preferred pastimes, your most-used programming languages or frameworks, or the subjects you spend the most time learning. It’s helpful to use the syntax –: below the header row to right-align a table column that contains numbers.

  • Visit the Edit file tab once again.
  • To introduce yourself, add a ## About me header and a brief bio, like the one below, two lines after the </picture> tag.
## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.
  • Insert a table by copying and pasting the following markup two lines below this text.
| Rank | THING-TO-RANK |


|     1|               |

|     2|               |

|     3|               |
  • Replace THING-TO-RANK with “Languages,” “Hobbies,” or anything else in the column on the right, then fill in the column with your list of items.
  • Click the Preview tab to verify that the table has been rendered correctly.

Including a collapsed section

The details> tag can be used to create an expandable collapsed section to keep your content organized.

  • Wrap your table in details> tags like in the example below if you want to create a collapsed section for the table you built.

<summary>My top THINGS-TO-RANK</summary>


  • Replace THINGS-TO-RANK with anything you rated in your table in between the summary> tags.
  • You can optionally add the open attribute to the details> element to have the section display as open by default.
<details open>
  • Click the Preview tab to verify that the collapsed part has been rendered correctly.
See Also  How to Make a GitHub Repository Private

Including a quote

There are a ton of other formatting possibilities in Markdown. To divide your page into sections and format your favorite quote, add a horizontal rule here.

  • Add a horizontal rule by entering three or more dashes two lines below the /details> tag at the bottom of your document.
  • Add a quote by entering markup similar to the following below the —- line.
  • Choose a different quote to use in place of QUOTE. Alternately, replicate the passage.
  • Click the Preview tab to verify that everything has been rendered appropriately.

Including a comment

To add a comment that won’t appear in the output, use HTML comment syntax. To remind yourself to update your README later, leave a comment here.

  • Use the code below to add a comment two lines behind the ## About me heading.
<!-- COMMENT -->
  • Change COMMENT to a “to-do” item that will serve as a reminder to complete it later.
  • Click the Preview tab to see if your comment was hidden in the output.

Saving your work

When you’re satisfied with your modifications, click Commit changes to preserve your profile README. 

Any user who visits your profile will be able to see your modifications if you commit them directly to the main branch. You can choose to Create a new branch for this commit and launch a pull request if you want to store your work but aren’t ready to make it publicly accessible on your profile.


As a developer, you need to know how to write a README to document your project. This is important because the README is the first file someone will see when they come across your project, so it should be short but detailed.

  • It will help your project stand out from the rest. Make sure that your project is good as well.
  • It will help you think about what your project needs to do and how it needs to do it.
  • It will help you get better at writing.

Share This Post

Newest Articles

How to Get a GitHub Access Token for Personal Access

No longer have access to your personal GitHub repository? You can use the GitHub Access Token to open it. Read the full guide here!

How to Make a GitHub Repository Private

Developers can now create a private GitHub repository in the free tier as of January 7, 2019. Read how to get the private repository feature on GitHub here!

3 Methods of How to Install Android SDK Repository

Android is one of the most used operating systems for software development. Read the full guide on how to get the Android SDK here!

How to Turn Off Android Developer Mode

Android Developer Options allows you to access hidden features. If you want to deactivate it, follow this simple guide to turn it off!

5 Simple Ways How to Get Cookie Clicker GitHub

How to get and use Cookie Clicker on GitHub? You can find the simple steps and cheats for Cookie Clicker in this article!

How to Integrate Jira with GitHub in 6 Easy Steps

If you use Jira for your work and need to integrate with another organization that uses GitHub, integration is what you require. Read the details here!