• Because of this, GitHub will recognize the README.md file and display the text, making it the focal point of your repository. How should the layout of a README.md file be structured for a project.
• GitHub Flavored Markdown. GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com. Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests.

1. Git Readme Md
2. Github Readme.md Markdown

README.md files are created using Markdown which you can use to format text and add images. The GitHub Guide for Mastering Markdown has some helpful hints that can get you started with this.

🍿 3 min. read

GitHub recently released a feature that allows users to create a profile-level README to display prominently on their GitHub profile. This article walksthrough how to access this new feature. I'll also be sharing some fun GitHub profiles I've seen so far. I'd love it if you shared yours with me on Twitter @indigitalcolor.

The above GIF shows what my README looks like at the time of this writing. You may notice I was recently selected to be GitHub star!

Table of Contents

Why READMEs?

Git Readme Md

The GitHub profile-level README feature allows more content than the profile bio, supports markdown which means you can play around with the content more visually (Did someone say GIFs!?) and the README is significantally more visible as it is placed above pinned repositories and takes up as much space above the fold of the webpage as you like.

A solid README is a core-component of well-documented software and often encourages collaboration by sharing helpful context with contributors. In my opinion, a profile-level README seems like a great extension of a convention a lot of GitHub users are already familiar with. If you're looking to make project-level READMEs more awesome and helpful check out matiassingers/awesome-readme for resources and examples of compelling READMEs.

How do I create a profile README?

The profile README is created by creating a new repository that’s the same name as your username. For example, my GitHub username is m0nica so I created a new repository with the name m0nica. Note: at the time of this writing, in order to access the profile README feature, the letter-casing must match your GitHub username.

Already have a repo-named username/username?

If you are interested in setting up a profile-level README then you can rename the repositoryor repurpose its existing README based on what makes the most sense in your particular situation.

1. Create a new repository with the same name (including casing) as your GitHub username: https://github.com/new

2. Create a README.md file inside the new repo with content (text, GIFs, images, emojis, etc.)

3. Commit your fancy new README!

   • If you're on GitHub's web interface you can choose to commit directly to the repo's main branch (i.e., master or main) which will make it immediately visible on your profile)

4. Push changes to GitHub (if you made changes locally i.e., on your computer and not github.com)

Fun READMEs

The GitHub README profiles are written in Markdown which means you aren't just limited to texts and links, you can include GIFs and images. Need to brush up on Markdown Syntax? Check out this Markdown Cheatsheet.

hey, check out the new @github profile README! this is a really nice addition — I love that we can add some context (and/or nonsense) to our GitHub profiles now 😍
see mine: https://t.co/Cvrch1DVFD
thanks to @cassidoo for the heads up that this went live! pic.twitter.com/xMTeBgRLh0

— Jason Lengstorf (@jlengstorf) July 9, 2020

It's not as creative as @sudo_overflow's readme, but here's what I came up with. I also plan on adding some text below the image with links to my resume, etc. pic.twitter.com/C6b8tNDo1z

— donavon 'wyld' west (@donavon) July 9, 2020

Is this how we suppose use github's readme? pic.twitter.com/XvLvCUC6iD

— Pouya (@Saadeghi) July 9, 2020

If you're really ambitious you can use GitHub actions or other automation like bdougieYO or simonw to dynamically pull data into your README:

Check it out. I made MySpace but on @github.https://t.co/p4DWP4DxRR - My list is power by a GitHub Action workflow 😏 pic.twitter.com/PN80mFCqOE

— bdougie on the internet (@bdougieYO) July 10, 2020

Made myself a self-updating GitHub personal README! It uses a GitHub Action to update itself with my latest GitHub releases, blog entries and TILs https://t.co/Eve7FOrwYKpic.twitter.com/oJPXLtFdgM

— Simon Willison (@simonw) July 10, 2020

Serverless functions can also be used to dynamically generate information (for example your current Spotify activity):

I embedded a @Spotify Now Playing widget in my @github profile README!
It's an SVG rendered on the fly via @vercel serverless function, included in the README via <img> tag.
Supremely over-engineered, but I discovered lots of fun hacks in the process.https://t.co/Z8TBE9WxRypic.twitter.com/wdKw0maPKp

— Nate Moore (@n_moore) July 12, 2020

I'm a huge proponent that folks should maintain a website they have complete ownership over (even if it's a no-code website solution) but this is tempting...

I just created my @github profile README as well with a bunch of badges. This is really a brilliant idea. We may no longer need to maintain our personal website. We can write blogs as issues, manage Wiki and task board, free traffic analytics and CI/CD. https://t.co/zSXZKT6a20pic.twitter.com/mK9OWXG9iH

— Yuan Tang (@TerryTangYuan) July 10, 2020

hey, so we heard ya & are trying out a thing where you CAN have a readme on your @github profile... @mikekavouras built it btw! re: https://t.co/UC6q3qHjjRpic.twitter.com/kB0kafgovY

— kathy ☁️ (@pifafu) May 27, 2020

I've been inspired by the creative READMEs I've seen so far and am looking forward to seeing all kinds of profiles in the upcoming months.

This article was published on July 11, 2020.

Webmentions

482167

Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.

What you will learn:

• How the Markdown format makes styled collaborative editing easy
• How Markdown differs from traditional formatting approaches
• How to use Markdown to format text
• How to leverage GitHub’s automatic Markdown rendering
• How to apply GitHub’s unique Markdown extensions

What is Markdown?

Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

You can use Markdown most places around GitHub:

• Comments in Issues and Pull Requests
• Files with the .md or .markdown extension

For more information, see “Writing on GitHub” in the GitHub Help.

Examples

Syntax guide

Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.

Headers

Emphasis

Lists

Unordered

Ordered

Images

Links

Blockquotes

Inline code

GitHub Flavored Markdown

GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com.

Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests. These include @mentions as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.

Syntax highlighting

Github Readme.md Markdown

Here’s an example of how you can use syntax highlighting with GitHub Flavored Markdown:

You can also simply indent your code by four spaces:

Here’s an example of Python code without syntax highlighting:

Task Lists

If you include a task list in the first comment of an Issue, you will get a handy progress indicator in your issue list. It also works in Pull Requests!

Tables

You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe |:

Would become:

First Header	Second Header
Content from cell 1	Content from cell 2
Content in the first column	Content in the second column

SHA references

Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub.

Issue references within a repository

Any number that refers to an Issue or Pull Request will be automatically converted into a link.

Username @mentions

Typing an @ symbol, followed by a username, will notify that person to come and view the comment. This is called an “@mention”, because you’re mentioning the individual. You can also @mention teams within an organization.

Automatic linking for URLs

Any URL (like http://www.github.com/) will be automatically converted into a clickable link.

Strikethrough

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.

Emoji

GitHub supports emoji!

To see a list of every image we support, check out the Emoji Cheat Sheet.

Last updated Jan 15, 2014