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 about-me.md.
Making changes to your profile README
You can tell the GitHub.com 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 README.md file as its initial content.
- The template text (starting ### Hello) that is automatically added when you create the file is removed by editing the README.md 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 README.md file.
<picture> <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE"> <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE"> <img alt="YOUR-ALT-TEXT" src="YOUR-DEFAULT-IMAGE"> </picture>
- 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.
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.
<details> <summary>My top THINGS-TO-RANK</summary> YOUR TABLE </details>
- 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.
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.
> QUOTE
- 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.
Tips
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.
