Quickstart for writing on GitHub
Learn advanced formatting features by creating a README for your GitHub profile.
Introduction
Markdown is an easy-to-read, easy-to-write language for formatting plain text. You can use Markdown syntax, along with some additional HTML tags, to format your writing on GitHub, in places like repository READMEs and comments on pull requests and issues. In this guide, you’ll learn some advanced formatting features by creating or editing a README for your GitHub profile.
If you’re new to Markdown, you might want to start with «Basic writing and formatting syntax» or the Communicate using Markdown GitHub Skills course.
If you already have a profile README, you can follow this guide by adding some features to your existing README, or by creating a gist with a Markdown file called something like about-me.md . For more information, see «Creating gists.»
Creating or editing your profile README
Your profile README lets you share information about yourself with the community on GitHub.com. The README is displayed at the top of your profile page.
If you don’t already have a profile README, you can add one.
- Create a repository with the same name as your GitHub username, initializing the repository with a README.md file. For more information, see «Managing your profile README.»
- Edit the README.md file and delete the template text (beginning ### Hi there ) that is automatically added when you create the file.
If you already have a profile README, you can edit it from your profile page.
In the upper-right corner of any GitHub page, click your profile photo, then click Your profile.
next to your profile README.
Adding an image to suit your visitors
You can include images in your communication on GitHub. Here, you’ll add a responsive image, such as a banner, to the top of your profile README.
By using the HTML <picture> element with the prefers-color-scheme media feature, you can add an image that changes depending on whether a visitor is using light or dark mode. For more information, see «Managing your theme settings.»
Copy and paste the following markup into your README.md file.
Replace the placeholders in the markup with the URLs of your chosen images. Alternatively, to try the feature first, you can copy the URLs from our example below.
- Replace YOUR-DARKMODE-IMAGE with the URL of an image to display for visitors using dark mode.
- Replace YOUR-LIGHTMODE-IMAGE with the URL of an image to display for visitors using light mode.
- Replace YOUR-DEFAULT-IMAGE with the URL of an image to display in case neither of the other images can be matched, for example if the visitor is using a browser that does not support the prefers-color-scheme feature.
To make the image accessible for visitors who are using a screen reader, replace YOUR-ALT-TEXT with a description of the image.
To check the image has rendered correctly, click the Preview tab.
For more information on using images in Markdown, see «Basic writing and formatting syntax.»
Example of a responsive image
How the image looks
Adding a table
You can use Markdown tables to organize information. Here, you’ll use a table to introduce yourself by ranking something, such as your most-used programming languages or frameworks, the things you’re spending your time learning, or your favorite hobbies. When a table column contains numbers, it’s useful to right-align the column by using the syntax —: below the header row.
Return to the Edit file tab.
To introduce yourself, two lines below the </picture> tag, add an ## About me header and a short paragraph about yourself, like the following.
Two lines below this paragraph, insert a table by copying and pasting the following markup.
In the column on the right, replace THING-TO-RANK with «Languages,» «Hobbies,» or anything else, and fill in the column with your list of things.
To check the table has rendered correctly, click the Preview tab.
Example of a table
How the table looks
Adding a collapsed section
To keep your content tidy, you can use the <details> tag to create an expandible collapsed section.
To create a collapsed section for the table you created, wrap your table in <details> tags like in the following example.
Between the <summary> tags, replace THINGS-TO-RANK with whatever you ranked in your table.
Optionally, to make the section display as open by default, add the open attribute to the <details> tag.
To check the collapsed section has rendered correctly, click the Preview tab.
Example of a collapsed section
How the collapsed section looks
Adding a quote
Markdown has many other options for formatting your content. Here, you’ll add a horizontal rule to divide your page and a blockquote to format your favorite quote.
At the bottom of your file, two lines below the </details> tag, add a horizontal rule by typing three or more dashes.
Below the — line, add a quote by typing markup like the following.
Replace QUOTE with a quote of your choice. Alternatively, copy the quote from our example below.
To check everything has rendered correctly, click the Preview tab.
Example of a quote
How the quote looks
Adding a comment
You can use HTML comment syntax to add a comment that will be hidden in the output. Here, you’ll add a comment to remind yourself to update your README later.
Two lines below the ## About me header, insert a comment by using the following markup.
Replace COMMENT with a «to-do» item you remind yourself to do something later (for example, to add more items to the table).
To check your comment is hidden in the output, click the Preview tab.
Example of a comment
Saving your work
When you’re happy with your changes, save your profile README by clicking Commit changes.
Committing directly to the main branch will make your changes visible to any visitor on your profile. If you want to save your work but aren’t ready to make it visible on your profile, you can select Create a new branch for this commit and start a pull request.
Next steps
- Continue to learn about advanced formatting features. For example, see «Creating diagrams» and «Creating and highlighting code blocks.»
- Use your new skills as you communicate across GitHub, in issues, pull requests, and discussions. For more information, see «Communicating on GitHub.»
Help and support
Help us make these docs great!
All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.
Русские Блоги
1: Поместите изображение, которое хотите загрузить, в папку, и обратите внимание, что в названии изображения не могут быть скобок.
(Вам не нужно делать этот шаг, поместите его в папку, чтобы вы могли лучше находить изображения, которые хотите загрузить)
2: Найдите склад, куда вы хотите загрузить изображения, в GitHub и нажмите «Обновить файлы».
Выберите картинку, которую хотите загрузить
Как показано ниже, появится изображение, которое вы хотите загрузить.
Щелкните фиксацию ниже.
3: Вернитесь на склад, нажмите на свое изображение и скопируйте ссылку на верхнее изображение на странице.
4: Откройте README.md и заполните файл README.md в следующем формате
Сохраните отправку. Вернувшись на склад, вы увидите картинку, которую хотите загрузить, на README.md.
Вышеупомянутая загрузка прошла успешно! Не правда ли, просто! Попробуйте! ! !
3 Ways to Add an Image to GitHub README
Images often come in handy alongside documentation. Here are a few methods for adding them to your README and other markdown files.
Images can be a great way to enhance your documentation in README files or other markdown documentation. While there is a standard way to add an image in markdown, the nuance is in the image's source. Here are three methods for adding images to markdown files in a GitHub repository.
Markdown Syntax
The original documentation specifies that images should be written like so:
HTML code is also valid within most markdown renderers, including GitHub's flavor. That means you could also render an the image above like this:
This is a great option if you want to add a little custom styling to your image. For example, if you want to control the size or alignment of the image, you might do something like this:
Method #1: Local File
The first method is to commit the image directly to your GitHub repository. When you do that, you can use a path to that file for the src , which should be relative from the markdown file.
In other words, if you place an image file in the root your project as my-image.jpg , you could then render the image in your projects main README.md file like this ( title omitted for simplicity):
Let's say the image file was instead in an images directory. Then your code in the project's main README file would look like this:
Now, let's say that you have another README file in your src directory, but your image is still in the images directory. Then your relative path looks like this:
This approach is a quick and easy option, as long as you don't have too many images to manage. If you end up using a lot of images, I'd consider another route .
Method #2: Remote File
Another option is to use some external file hosting service to provide your image, such as S3 or Dropbox. In this case, you could get the direct and full URL to the image and then use that.
Method #3: Uploaded File
Lastly, you could use GitHub to host the image for you. This one is a little goofy, but it totally works!
The trick is to add them to some comment — an issue, pull request or discussion — and then grab the resulting URL.
You can drag and drop the image from your computer to a comment field in GitHub. Wait for the file to upload and then the URL to the image is right there! You don't even have to submit the issue if you don't want to (although that may limit the image's lifespan).
Unlike the other two options, I see two issues with this approach:
- On its own, it becomes difficult to know the source of the image. Maybe that's not a big deal, or maybe you have a way to streamline it — e.g. all your images go into a single "Images" issue that stays open.
- The purpose of images in comments is technically to serve the comment. It's possible GitHub changes these URLs without notifying you.
Inspiration & Resources
This post was originally inspired by this tweet from @DavidDarnes:
Haha nice! FYI if you upload those readme images in a new GitHub comment and it'll give you the image paths back to put them in your readme, then you won't have them cluttering the repo 😶
— Dave 🧱 (@DavidDarnes) January 18, 2021
I ended up being more comprehensive than just this singular suggestion, which came to be more in-line with this StackOverflow question.
The Least You Need to Know About GitHub Pages
The least you need to know about GitHub Pages is laser-focused on one thing: showing how to get a working informational website up and running as fast as possible using GitHub Pages, using only the GitHub website.
Adding images to your GitHub Pages site
The Jekyll publishing system used by GitHub Pages expects you to have an assets directory, and that’s where image files should be placed. By convention they go into an images subdirectory (full path /docs/assets/images but that’s not a firm requirement. They can be anywhere in the /docs/assets path.
Create a directory called /docs/assets
- If you haven’t yet created an assets directory, read Adding an assets directory to GitHub Pages and follow those steps to create a directory at /docs/assets .
Upload images to the /docs/assets directory
On GitHub, navigate to the /docs/assets directory.
Click the Add file button, then choose Upload files