Now that you have the Markdown basics figured out, it's time to learn how to edit your README. Following repository creation, GitHub took you to the README. If you left the browser window alone, you should be looking at something similar to the following. Click the green Edit README button to continue.

If you clicked away from it or refreshed, the green button may not be present, in which case, you're looking at something similar to the following. Click the "pencil" shaped Edit button to continue.

Either way, you'll open the GitHub file editor, which includes two major sections: the file content editor, and the Commit changes section. First up: the editor.

GitHub File Editor

The top section is the file editor. This section is where you'll spend most of your time when editing your README file. The green alert won't show up on any other file you edit on GitHub, as it is related specifically to this file.

At the top of this section you can edit the filename (indicated by the magenta arrow). Don't do that! It must be named to work for this purpose. Below the alert is the actual content editor (indicated by the orange arrow).

There are two key features to the file content editor. There are two tabs at the top, titled Edit file and Preview.

The file editor begins in the Edit file tab. Below it, is the content editor itself. As you can see, this README was generated with preexisting content. Any README you generate using the checkbox at repository creation will have some content, but this README is special, and therefore, so is its content.

When it comes down to it, though, one of the greatest things about the GitHub file editor is the Preview tab. The Preview tab is magical. It allows you to view your content the way GitHub will render it once you "save" the file. So, you can make incremental changes, and view how they will appear every step of the way. That way, you know for certain the content you added looks exactly like you want it to. And, if it doesn't? You can continue to update it and verify it until it does.

Here is what the content looks like in the editor (on top), and how it is rendered by GitHub in the preview (on the bottom).

You may have noticed that the file preview doesn't quite match the file content. The only thing rendered was the first line and the third line added by you. That is because the rest of the Markdown is what is referred to in programming as "commented out". Commenting something out means you can include something in your file, such as a note or comment, and have it be ignored when the file is rendered. When you generate your personal repo and include a README, it comes populated with a short list of prompts to get you started. GitHub provides a starting point for profile content commented out to allow you to choose to add it to your profile or not.

Editing Content

Now that you've explored the editor, it's time to dig into editing the content. "Hi there" is pretty generic. How about adding an intro to yourself by name?

Click the Edit file tab if you're not already in the editor. Click to line 2 in the code and hit enter once to put a line between the header and where you're about to type. You should now be on line 3. Add the text, "I'm <your name>!" The top of your file should look something like the following.

Click the Preview tab. You've now introduced yourself!

You now know how to do basic content editing on your README. You'll get into more detail later in this guide.

Committing Content

As with any file on your computer, once you edit it, you need to save your changes. On GitHub, "saving" your changes is called committing, and the point at which you save your file is called a commit. Creating commits regularly ensures you never lose much work. This is where the second section on this page comes in - the Committing changes section.

Scroll down to the bottom of the page, and you'll find the Committing changes section. Yours should look something like this.

The first box is where you can add your commit title. It currently says in grey "Create", and if left as-is, the commit title will be "Create". This is the only box for which this is the case. Commit titles are typically less than 50 characters, so you want to be brief and concise. This is what will be associated with your save on GitHub. While you can leave it as the default, it can also be really helpful to update it to something more specific to your change so you know at a glance what your last update was.

The second, larger box is for your commit message. This is optional. Though it also has grey text, it will be left empty if you do not add your own text. You're welcome to add more details in the commit message box regarding your changes, but it is not necessary to do.

If you have more than one email address associated with GitHub, you'll see the drop-down under the commit message box allowing you to choose which email address you want associated with this commit.

Finally, there are two radio dials. The first says "Commit directly to the main branch." The second says "Create a new branch for this commit and start a pull request." Since this is your personal repository, and you are the only one working on this file, you'll leave this section in the default state with the first dial selected.

Since you added an intro,  you can update the commit title to "Added basic intro." As there's not much else to it, it's fine to leave the commit message blank. So your Commit changes section should now look like this.

The final step is to click the green Commit changes button.

This will commit your changes and return you to the README file as it shows up on GitHub.

That's what goes into editing your README and committing your changes to save them to GitHub!

Obviously, you'll want to add more content than that. What else can you add? For those who aren't sure where to begin, the next section discusses ideas for profile content.

This guide was first published on Jul 06, 2022. It was last updated on Jun 07, 2022.

This page (Edit Your README) was last updated on Jun 09, 2022.

Text editor powered by tinymce.