Basic writing and formatting syntax

In this article.

Create sophisticated formatting for your prose and code on GitHub with simple syntax.

To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the hierarchy level and typeface size of the heading.

Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to indicate descending hierarchy level.

When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section.

Screenshot of the README file in the GitHub Docs open source repository with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.

Styling text

You can indicate emphasis with bold, italic, strikethrough, subscript, or superscript text in comment fields and .md files.

Quoting text

You can quote text with a > .

Quoted text is indented, with a different type color.

Screenshot of rendered GitHub Markdown showing sample quoted text. The quote is indented with a vertical line on the left, and its text is dark gray rather than black.

Note: When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing R . You can quote an entire comment by clicking , then Quote reply . For more information about keyboard shortcuts, see " Keyboard shortcuts ."

Quoting code

You can call out code or a command within a sentence with single backticks. The text within the backticks will not be formatted. You can also press the Command + E (Mac) or Ctrl + E (Windows/Linux) keyboard shortcut to insert the backticks for a code block within a line of Markdown.

Screenshot of rendered GitHub Markdown showing the appearance of characters surrounded by backticks. The words "git status" appear in a fixed-width typeface, highlighted in light gray.

To format code or text into its own distinct block, use triple backticks.

Screenshot of rendered GitHub Markdown showing a code block. The words "git status," "git add," and "git commit" appear in a fixed-width typeface, highlighted in light gray.

For more information, see " Creating and highlighting code blocks ."

If you are frequently editing code snippets and tables, you may benefit from enabling a fixed-width font in all comment fields on GitHub. For more information, see " About writing and formatting on GitHub ."

Supported color models

In issues, pull requests, and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.

Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color. #ffffff shows a white circle, and #000000 shows a black circle.

Here are the currently supported color models.

  • A supported color model cannot have any leading or trailing spaces within the backticks.
  • The visualization of the color is only supported in issues, pull requests, and discussions.

You can create an inline link by wrapping link text in brackets [ ] , and then wrapping the URL in parentheses ( ) . You can also use the keyboard shortcut Command + K to create a link. When you have text selected, you can paste a URL from your clipboard to automatically create a link from the selection.

You can also create a Markdown hyperlink by highlighting the text and using the keyboard shortcut Command + V . If you'd like to replace the text with the link, use the keyboard shortcut Command + Shift + V .

This site was built using [GitHub Pages](

Screenshot of rendered GitHub Markdown showing how text within brackets, "GitHub Pages," appears as a blue hyperlink.

Note: GitHub automatically creates links when valid URLs are written in a comment. For more information, see " Autolinked references and URLs ."

Section links

You can link directly to a section in a rendered file by hovering over the section heading to expose .

Screenshot of a README for a repository. To the left of a section heading, a link icon is outlined in dark orange.

Relative links

You can define relative links and image paths in your rendered files to help readers navigate to other files in your repository.

A relative link is a link that is relative to the current file. For example, if you have a README file in root of your repository, and you have another file in docs/ , the relative link to in your README might look like this:

GitHub will automatically transform your relative link or image path based on whatever branch you're currently on, so that the link or path always works. The path of the link will be relative to the current file. Links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../ .

Relative links are easier for users who clone your repository. Absolute links may not work in clones of your repository - we recommend using relative links to refer to other files within your repository.

You can display an image by adding ! and wrapping the alt text in [ ] . Alt text is a short text equivalent of the information in the image. Then, wrap the link for the image in parentheses () .

![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](

Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.

GitHub supports embedding images into your issues, pull requests, discussions, comments and .md files. You can display an image from your repository, add a link to an online image, or upload an image. For more information, see " Uploading assets ."

Note: When you want to display an image that is in your repository, use relative links instead of absolute links.

Here are some examples for using relative links to display an image.

Note : The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images.

For more information, see " Relative Links ."

Specifying the theme an image is shown to

You can specify the theme an image is displayed for in Markdown by using the HTML <picture> element in combination with the prefers-color-scheme media feature. We distinguish between light and dark color modes, so there are two options available. You can use these options to display images optimized for dark or light backgrounds. This is particularly helpful for transparent PNG images.

For example, the following code displays a sun image for light themes and a moon for dark themes:

The old method of specifying images based on the theme, by using a fragment appended to the URL ( #gh-dark-mode-only or #gh-light-mode-only ), is deprecated and will be removed in favor of the new method described above.

You can make an unordered list by preceding one or more lines of text with - , * , or + .

Screenshot of rendered GitHub Markdown showing a bulleted list of the names of the first three American presidents.

To order your list, precede each line with a number.

Screenshot of rendered GitHub Markdown showing a numbered list of the names of the fourth, fifth, and sixth American presidents.

Nested Lists

You can create a nested list by indenting one or more list items below another item.

To create a nested list using the web editor on GitHub or a text editor that uses a monospaced font, like Visual Studio Code , you can align your list visually. Type space characters in front of your nested list item until the list marker character ( - or * ) lies directly below the first character of the text in the item above it.

Note : In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using Tab or Shift + Tab respectively.

Screenshot of Markdown in Visual Studio Code showing how indented bullets align vertically with the first letter of the text lines above them.

To create a nested list in the comment editor on GitHub, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item.

In this example, you could add a nested list item under the list item 100. First list item by indenting the nested list item a minimum of five spaces, since there are five characters ( 100 . ) before First list item .

Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right.

You can create multiple levels of nested lists using the same method. For example, because the first nested list item has seven characters ( ␣␣␣␣␣-␣ ) before the nested list content First nested list item , you would need to indent the second nested list item by at least two more characters (nine spaces minimum).

Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.

For more examples, see the GitHub Flavored Markdown Spec .

To create a task list, preface list items with a hyphen and space followed by [ ] . To mark a task as complete, use [x] .

Screenshot showing the rendered version of the markdown. The references to issues are rendered as issue titles.

If a task list item description begins with a parenthesis, you'll need to escape it with \ :

- [ ] \(Optional) Open a followup issue

For more information, see " About task lists ."

Mentioning people and teams

You can mention a person or team on GitHub by typing @ plus their username or team name. This will trigger a notification and bring their attention to the conversation. People will also receive a notification if you edit a comment to mention their username or team name. For more information about notifications, see " About notifications ."

Note: A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization.

@github/support What do you think about these updates?

Screenshot of rendered GitHub Markdown showing how the team mention "@github/support" renders as bold, clickable text.

When you mention a parent team, members of its child teams also receive notifications, simplifying communication with multiple groups of people. For more information, see " About teams ."

Typing an @ symbol will bring up a list of people or teams on a project. The list filters as you type, so once you find the name of the person or team you are looking for, you can use the arrow keys to select it and press either tab or enter to complete the name. For teams, enter the @organization/team-name and all members of that team will get subscribed to the conversation.

The autocomplete results are restricted to repository collaborators and any other participants on the thread.

Referencing issues and pull requests

You can bring up a list of suggested issues and pull requests within the repository by typing # . Type the issue or pull request number or title to filter the list, and then press either tab or enter to complete the highlighted result.

For more information, see " Autolinked references and URLs ."

Referencing external resources

If custom autolink references are configured for a repository, then references to external resources, like a JIRA issue or Zendesk ticket, convert into shortened links. To know which autolinks are available in your repository, contact someone with admin permissions to the repository. For more information, see " Configuring autolinks to reference external resources ."

Uploading assets

You can upload assets like images by dragging and dropping, selecting from a file browser, or pasting. You can upload assets to issues, pull requests, comments, and .md files in your repository.

Using emoji

You can add emoji to your writing by typing :EMOJICODE: , a colon followed by the name of the emoji.

@octocat :+1: This PR looks great - it's ready to merge! :shipit:

Screenshot of rendered GitHub Markdown showing how emoji codes for +1 and shipit render visually as emoji.

Typing : will bring up a list of suggested emoji. The list will filter as you type, so once you find the emoji you're looking for, press Tab or Enter to complete the highlighted result.

For a full list of available emoji and codes, see the Emoji-Cheat-Sheet .

You can create a new paragraph by leaving a blank line between lines of text.

You can add footnotes to your content by using this bracket syntax:

The footnote will render like this:

Screenshot of rendered Markdown showing superscript numbers used to indicate footnotes, along with optional line breaks inside a note.

Note : The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown.

Footnotes are not supported in wikis.

Alerts are an extension of the blockquote syntax that you can use to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the importance of the content. Alert syntax is supported in:

  • Pull requestes
  • Markdown files
  • Discussions

We recommend restricting the use of alerts to one or two per article to avoid overloading the reader. Consecutive alerts should be avoided.

Multiple types of alerts are available. You can add an alert with a special blockquote line that specifies the alert type, and then add the alert information in a standard blockquote immediately after.

Here are the rendered alerts.

Screenshot of rendered Markdown alerts showing how Note, Tips, Important, Warning, and Caution render with different colored text and icons.

Hiding content with comments

You can tell GitHub to hide content from the rendered Markdown by placing the content in an HTML comment.

Ignoring Markdown formatting

You can tell GitHub to ignore (or escape) Markdown formatting by using \ before the Markdown character.

Let's rename \*our-new-project\* to \*our-old-project\*.

Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics. The text reads, "Let's rename our-new-project to our-old-project."

For more information on backslashes, see Daring Fireball's " Markdown Syntax ."

Note : The Markdown formatting will not be ignored in the title of an issue or a pull request.

Disabling Markdown rendering

When viewing a Markdown file, you can click Code at the top of the file to disable Markdown rendering and view the file's source instead.

Screenshot of a Markdown file in a GitHub repository showing options for interacting with the file. A button, labeled "Code", is outlined in dark orange.

Disabling Markdown rendering enables you to use source view features, such as line linking, which is not possible when viewing rendered Markdown files.

Further reading

  • GitHub Flavored Markdown Spec
  • " About writing and formatting on GitHub "
  • " Working with advanced formatting "
  • " Quickstart for writing on GitHub "

Getting Started

An overview of Markdown, how it works, and what you can do with it.

What is Markdown?

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.

Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.

For example, to denote a heading, you add a number sign before it (e.g., # Heading One ). Or to make a phrase bold, you add two asterisks before and after it (e.g., **this text is bold** ). It may take a while to get used to seeing Markdown syntax in your text, especially if you’re accustomed to WYSIWYG applications. The screenshot below shows a Markdown file displayed in the Visual Studio Code text editor .

Markdown file in the Visual Studio Code text editor

You can add Markdown formatting elements to a plaintext file using a text editor application. Or you can use one of the many Markdown applications for macOS, Windows, Linux, iOS, and Android operating systems. There are also several web-based applications specifically designed for writing in Markdown.

Depending on the application you use, you may not be able to preview the formatted document in real time. But that’s okay. According to Gruber , Markdown syntax is designed to be readable and unobtrusive, so the text in Markdown files can be read even if it isn’t rendered.

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Why Use Markdown?

You might be wondering why people use Markdown instead of a WYSIWYG editor. Why write with Markdown when you can press buttons in an interface to format your text? As it turns out, there are several reasons why people use Markdown instead of WYSIWYG editors.

Markdown can be used for everything. People use it to create websites , documents , notes , books , presentations , email messages , and technical documentation .

Markdown is portable. Files containing Markdown-formatted text can be opened using virtually any application. If you decide you don’t like the Markdown application you’re currently using, you can import your Markdown files into another Markdown application. That’s in stark contrast to word processing applications like Microsoft Word that lock your content into a proprietary file format.

Markdown is platform independent. You can create Markdown-formatted text on any device running any operating system.

Markdown is future proof. Even if the application you’re using stops working at some point in the future, you’ll still be able to read your Markdown-formatted text using a text editing application. This is an important consideration when it comes to books, university theses, and other milestone documents that need to be preserved indefinitely.

Markdown is everywhere. Websites like Reddit and GitHub support Markdown, and lots of desktop and web-based applications support it.

Kicking the Tires

The best way to get started with Markdown is to use it. That’s easier than ever before thanks to a variety of free tools.

You don’t even need to download anything. There are several online Markdown editors that you can use to try writing in Markdown. Dillinger is one of the best online Markdown editors. Just open the site and start typing in the left pane. A preview of the rendered document appears in the right pane.

Dillinger Markdown editor

You’ll probably want to keep the Dillinger website open as you read through this guide. That way you can try the syntax as you learn about it. After you’ve become familiar with Markdown, you may want to use a Markdown application that can be installed on your desktop computer or mobile device.

How Does it Work?

Dillinger makes writing in Markdown easy because it hides the stuff happening behind the scenes, but it’s worth exploring how the process works in general.

When you write in Markdown, the text is stored in a plaintext file that has an .md or .markdown extension. But then what? How is your Markdown-formatted file converted into HTML or a print-ready document?

The short answer is that you need a Markdown application capable of processing the Markdown file. There are lots of applications available — everything from simple scripts to desktop applications that look like Microsoft Word. Despite their visual differences, all of the applications do the same thing. Like Dillinger, they all convert Markdown-formatted text to HTML so it can be displayed in web browsers.

Markdown applications use something called a Markdown processor (also commonly referred to as a “parser” or an “implementation”) to take the Markdown-formatted text and output it to HTML format. At that point, your document can be viewed in a web browser or combined with a style sheet and printed. You can see a visual representation of this process below.

The Markdown Process

To summarize, this is a four-part process:

  • Create a Markdown file using a text editor or a dedicated Markdown application. The file should have an .md or .markdown extension.
  • Open the Markdown file in a Markdown application.
  • Use the Markdown application to convert the Markdown file to an HTML document.
  • View the HTML file in a web browser or use the Markdown application to convert it to another file format, like PDF.

From your perspective, the process will vary somewhat depending on the application you use. For example, Dillinger essentially combines steps 1-3 into a single, seamless interface — all you have to do is type in the left pane and the rendered output magically appears in the right pane. But if you use other tools, like a text editor with a static website generator, you’ll find that the process is much more visible.

What’s Markdown Good For?

Markdown is a fast and easy way to take notes, create content for a website, and produce print-ready documents.

It doesn’t take long to learn the Markdown syntax, and once you know how to use it, you can write using Markdown just about everywhere. Most people use Markdown to create content for the web, but Markdown is good for formatting everything from email messages to grocery lists.

Here are some examples of what you can do with Markdown.

Markdown was designed for the web, so it should come as no surprise that there are plenty of applications specifically designed for creating website content.

If you’re looking for the simplest possible way to create a website with Markdown files, check out . After you sign up for Blot, it creates a Dropbox folder on your computer. Just drag and drop your Markdown files into the folder and — poof! — they’re on your website. It couldn’t be easier.

If you’re familiar with HTML, CSS, and version control, check out Jekyll , a popular static site generator that takes Markdown files and builds an HTML website. One advantage to this approach is that GitHub Pages provides free hosting for Jekyll-generated websites. If Jekyll isn’t your cup of tea, just pick one of the many other static site generators available .

If you’d like to use a content management system (CMS) to power your website, take a look at Ghost . It’s a free and open-source blogging platform with a nice Markdown editor. If you’re a WordPress user, you’ll be happy to know there’s Markdown support for websites hosted on Self-hosted WordPress sites can use the Jetpack plugin .

Markdown doesn’t have all the bells and whistles of word processors like Microsoft Word, but it’s good enough for creating basic documents like assignments and letters. You can use a Markdown document authoring application to create and export Markdown-formatted documents to PDF or HTML file format. The PDF part is key, because once you have a PDF document, you can do anything with it — print it, email it, or upload it to a website.

Here are some Markdown document authoring applications I recommend:

  • Mac: MacDown , iA Writer , or Marked 2
  • iOS / Android: iA Writer
  • Windows: ghostwriter or Markdown Monster
  • Linux: ReText or ghostwriter
  • Web: Dillinger or StackEdit

In nearly every way, Markdown is the ideal syntax for taking notes. Sadly, Evernote and OneNote , two of the most popular note applications, don’t currently support Markdown. The good news is that several other note applications do support Markdown:

  • Obsidian is a popular Markdown note-taking application loaded with features.
  • Simplenote is a free, barebones note-taking application available for every platform.
  • Notable is a note-taking application that runs on a variety of platforms.
  • Bear is an Evernote-like application available for Mac and iOS devices. It doesn’t exclusively use Markdown by default, but you can enable Markdown compatibility mode.
  • Joplin is a note taking application that respects your privacy. It’s available for every platform.
  • Boostnote bills itself as an “open source note-taking app designed for programmers.”

If you can’t part with Evernote, check out Marxico , a subscription-based Markdown editor for Evernote, or use Markdown Here with the Evernote website.

Looking to self-publish a novel? Try Leanpub , a service that takes your Markdown-formatted files and turns them into an electronic book. Leanpub outputs your book in PDF, EPUB, and MOBI file format. If you’d like to create paperback copies of your book, you can upload the PDF file to another service such as Kindle Direct Publishing . To learn more about writing and self-publishing a book using Markdown, read this blog post .


Believe it or not, you can generate presentations from Markdown-formatted files. Creating presentations in Markdown takes a little getting used to, but once you get the hang of it, it’s a lot faster and easier than using an application like PowerPoint or Keynote. Remark ( GitHub project ) is a popular browser-based Markdown slideshow tool, as are Cleaver ( GitHub project ) and Marp ( GitHub project ). If you use a Mac and would prefer to use an application, check out Deckset or Hyperdeck .

If you send a lot of email and you’re tired of the formatting controls available on most email provider websites, you’ll be happy to learn there’s an easy way to write email messages using Markdown. Markdown Here is a free and open-source browser extension that converts Markdown-formatted text into HTML that’s ready to send.


Collaboration and team messaging applications are a popular way of communicating with coworkers and friends at work and home. These applications don’t utilize all of Markdown’s features, but the features they do provide are fairly useful. For example, the ability to bold and italicize text without using the WYSIWYG interface is pretty handy. Slack , Discord , Wiki.js , and Mattermost are all good collaboration applications.


Markdown is a natural fit for technical documentation. Companies like GitHub are increasingly switching to Markdown for their documentation — check out their blog post about how they migrated their Markdown-formatted documentation to Jekyll . If you write documentation for a product or service, take a look at these handy tools:

  • Read the Docs can generate a documentation website from your open source Markdown files. Just connect your GitHub repository to their service and push — Read the Docs does the rest. They also have a service for commercial entities .
  • MkDocs is a fast and simple static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown and configured with a single YAML configuration file. MkDocs has several built in themes , including a port of the Read the Docs documentation theme for use with MkDocs. One of the newest themes is MkDocs Material .
  • Docusaurus is a static site generator designed exclusively for creating documentation websites. It supports translations, search, and versioning.
  • VuePress is a static site generator powered by Vue and optimized for writing technical documentation.
  • Jekyll was mentioned earlier in the section on websites, but it’s also a good option for generating a documentation website from Markdown files. If you go this route, be sure to check out the Jekyll documentation theme .

Flavors of Markdown

One of the most confusing aspects of using Markdown is that practically every Markdown application implements a slightly different version of Markdown. These variants of Markdown are commonly referred to as flavors . It’s your job to master whatever flavor of Markdown your application has implemented.

To wrap your head around the concept of Markdown flavors, it might help to think of them as language dialects. People in New York City speak English just like the people in London, but there are substantial differences between the dialects used in both cities. The same is true for people using different Markdown applications. Using Dillinger to write with Markdown is a vastly different experience than using Ulysses .

Practically speaking, this means you never know exactly what a company means when they say they support “Markdown.” Are they talking about only the basic syntax elements , or all of the basic and extended syntax elements combined, or some arbitrary combination of syntax elements? You won’t know until you read the documentation or start using the application.

If you’re just starting out, the best advice I can give you is to pick a Markdown application with good Markdown support. That’ll go a long way towards maintaining the portability of your Markdown files. You might want to store and use your Markdown files in other applications, and to do that you need to start with an application that provides good support. You can use the tool directory to find an application that fits the bill.

Additional Resources

There are lots of resources you can use to learn Markdown. Here are some other introductory resources:

  • John Gruber’s Markdown documentation . The original guide written by the creator of Markdown.
  • Markdown Tutorial . An open source website that allows you to try Markdown in your web browser.
  • Awesome Markdown . A list of Markdown tools and learning resources.
  • Typesetting Markdown . A multi-part series that describes an ecosystem for typesetting Markdown documents using pandoc and ConTeXt .

Markdown Guide book cover

Take your Markdown skills to the next level.

Learn Markdown in 60 pages. Designed for both novices and experts, The Markdown Guide book is a comprehensive reference that has everything you need to get started and master Markdown syntax.

Want to learn more Markdown?

Don't stop now! 🚀 Star the GitHub repository and then enter your email address below to receive new Markdown tutorials via email. No spam!

How to Write a Good README File for Your GitHub Project

When I was first introduced to GitHub, I had no idea what it was or what it could do. Between you and me, I created the account because I was told every developer should have one where they push their code.

For the longest time as a beginner I did nothing with my account. But then, becuase of my passion in tech, I started following other developers and checking out their work on GitHub. And I noticed something they had in common: they all had cool projects and contributed to open source, but their projects also had detailed README files .

So my interest in what a README was grew, and I decided to try and add one in my projects, too. I won't lie – I did it in a hurry without any knowledge of how it should be done. And honestly it wasn't great at all. Check it out HERE .

And that was how it stayed for a period of time. But with practice and continuous learning I was able to change to some better documentation like THIS , which improved engagement with the project and helped other devs get involved.

It is also important to note that a good README will help you stand out among the large crowd of developers who put their work on GitHub.

In this article, we'll learn more about what a README file is and how to write one. First let's understand what we mean by a README file.

What is a README File?

In simple words, we can describe a README file as a guide that gives users a detailed description of a project you have worked on.

It can also be described as documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project.

It is essential for you as a developer to know how to document your project by writing a README because:

  • It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
  • It will make your project standout from a bunch of others. Also be sure your project is good too.
  • It will help you focus on what your project needs to deliver and how.
  • It will improve your writing skills, just as Friedrich Nietzsche said:
A good writer possesses not only his own spirit but also the spirit of his friends.

While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.

For instance, my earlier shared example of my first project does not have a good README. And even though the project was amazing, it would've been hard for a beginner to understand exactly what was expected when they cloned my repo. Who knows maybe it could've even been a coded virus.

With a project like this on GitHub, no matter how amazing it is, other devs won't be eager to work on it and try to figure it out without a good README.

Now, have a look at this project . Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.

You see, that's how powerful a well written README is and how it can change you project.

So, let's get started on how to write one for you too.

How to Write a Good README – a Step by Step Guide

A very important thing to note is that there's not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

From research and studying various README files, for sure there are some best practices that I have found. And that's what I will be sharing. As I usually tell my self:

Every day is a learning day.

So as you progress and advance in your career, you will develop your own ideas about what makes a good README and how to improve on it. Perhaps you'll even come up with your own unique guide.

Before we get started, it is also important to note that when you're writing your project's README, it should be able to answer the what , why , and the how of the project.

Here are some guide questions that will help you out:

  • What was your motivation?
  • Why did you build this project?
  • What problem does it solve?
  • What did you learn?
  • What makes your project stand out? If your project has a lot of features, consider adding a "Features" section and listing them here.

What to Include in your README

1. project's title.

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

2. Project Description

This is an important component of your project that many new developers often overlook.

Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

  • What your application does,
  • Why you used the technologies you used,
  • Some of the challenges you faced and features you hope to implement in the future.

3. Table of Contents (Optional)

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.

4. How to Install and Run the Project

If you are working on a project that a user needs to install or run locally in a machine like a "POS", you should include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment set and running.

5. How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

6. Include Credits

If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.

Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

7. Add a License

For most README files, this is usually considered the last part. It lets other developers know what they can and cannot do with your project.

We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.

The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link:

Up to this point what we have covered are the minimum requirements for a good README. But you might also want to consider adding the following sections to make it more eye catching and interactive.

Additional README Sections

Badges aren't necessary, but using them is a simple way of letting other developers know that you know what you're doing.

Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues etc...

Below is a screenshot from one of my projects that shows how you can make use of badges:


The good thing about this section is that it automatically updates it self.

Don't know where to get them from? Check out the badges hosted by . They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.

9. How to Contribute to the Project

This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.

Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.

Some of the most common guidelines include the Contributor Covenant and the Contributing guide . Thes docs will give you the help you need when setting rules for your project.

10. Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too

Extra points

Here are a few extra points to note when you're writing your README:

  • Keep it up-to-date - It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
  • Pick a language - We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn't familiar with English.

There you have it, everything you need to improve your README files, or even get you started with writing your first one.

At this point I am confident that you are in a position to add an interactive and inforamative guide to your next project or even an existing one and make your project standout.

There are many tools which you can also use to automatically generate a README for your project, but it's always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:

  • Make a README
  • README Generator

If you have read this far I really appreciate it. If you enjoyed this article and found it helpful, please share it so you can help another developer improve their projects.

I would love to see your newly crafted README file. Be sure to share a link with me via any of the links below:

Connect With me at Twitter | YouTube | LinkedIn | GitHub

Do share your valuable opinion, I appreciate your honest feedback!

Enjoy Coding ❤

Technical Writer ✍️ & Open-Source Enthusiast ❤ || Empowering Developers to Learn & Grow || Committed to Making a Meaningful Contribution to the Tech Community and Beyond.

If you read this far, thank the author to show them you care. Say Thanks

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started

Nov 24th, 2022

How to write a file.

Author Picture

Dhairya Shah

Software Engineer

In this article, you will learn what is a markdown file and how to write the markdown. Most of the time, you will find markdown files in GitHub repositories such as , , or .

What is a README file?

In simple words, a README file that guides users with a detailed explanation of the project/repository.

It describes the documentation with guidelines explaining the usage of the project. Usually, it describes the installation instructions.

It is very important to know how to document a readme as a developer, because:

  • It is the first thing a person sees when viewing your project repository.
  • It will make your project stand out from others. Also, be sure to have a good high-quality project.
  • It will help guide other developers who are contributing or want to contribute to the project.
  • It will help improve your documentation skills.

README files are written in markdown language. So, let’s understand what is markdown.

What is markdown?

Just like HTML, markdown is a lightweight markup language for creating formatted text using plain text. Markdown is actively used by developers and bloggers. Developers use markdown to write documentation as we discussed earlier README . It converts some plain text to the desired format in HTML. The simplicity and ease to understand are making the markdown more popular.


To create a markdown file, name the file with the .md extension. For example, .

Just like HTML, markdown has 6 levels of headings i.e h1 to h6. In markdown, we use # to add the heading. The number of the hash symbol will increase the heading type.

No special rules, just need to write simple text to write paragraphs,

Adding links to the markup looks like the following,

For example,

Bold text can be written by enclosing the text with double asterisks ** .

Italic Text

Italic text can be written by enclosing the text with a single asterisk * .


Strikethrough text can be written by enclosing the text with the double tilde symbol ~~

Adding images to markdown looks like following

Note: Don’t get confuse the image markup with link markup. Images have an exclamation mark ! at the start.

Tables can be written like the following,

If you want to write quotes just add a > symbol at the beginning of the line.

Code can be written by enclosing the text with a backtick `


The list can be written as order and unordered, for example:

Horizontal line

A horizontal line in the markdown file can be added simply by --- or *** :

Note: *** is for a thicker line.

There you have it, everything you need to improve your README files, or even get started with writing your first one.

Now you will confidently write the amazing READMEs for amazing projects.

There are many tools on the internet that allow you to write README for your next project. In case you want to check them out:

  • Make a README
  • README Generator
  • Mark2PDF Mark2PDF allows you to write and preview markdown code and save it in PDF format. I personally feel this very helpful tool.

Thanks for reading

Follow me on  Twitter

Thanks for reading!

Unrivalled writing experience

Rich markdown editor.

StackEdit’s Markdown syntax highlighting is unique. The refined text formatting of the editor helps you visualize the final rendering of your files.

write an md file

WYSIWYG controls

StackEdit provides very handy formatting buttons and shortcuts, thanks to PageDown, the WYSIWYG-style Markdown editor used by Stack Overflow.

Smart layout

Whether you write, you review, you comment… StackEdit's layout provides you with the flexibility you need, without sacrifice.

write an md file

Live preview with Scroll Sync

StackEdit’s Scroll Sync feature accurately binds the scrollbars of the editor panel and the preview panel to ensure that you always keep an eye on the output while writing.

Designed for web writers

Stay connected.

StackEdit can sync your files with Google Drive, Dropbox and GitHub. It can also publish them as blog posts to Blogger, WordPress and Zendesk. You can choose whether to upload in Markdown format, HTML, or to format the output using the Handlebars template engine.

write an md file


With StackEdit, you can share collaborative workspaces, thanks to the synchronization mechanism. If two collaborators are working on the same file at the same time, StackEdit takes care of merging the changes.

write an md file

StackEdit allows you to insert inline comments and embed collaborator discussions in your files, just as well as Microsoft Word and Google Docs.

write an md file

Write offline!

Even when you travel, StackEdit is still accessible and lets you write offline just like any desktop application. You have no excuse!

Extended Markdown support

write an md file

GitHub Flavored Markdown

StackEdit supports different Markdown flavors such as Markdown Extra, GFM and CommonMark. Each Markdown feature can be enabled or disabled at your convenience.

LaTeX mathematical expressions

StackEdit renders mathematics from LaTeX expressions inside your markdown file, as you would do on Stack Exchange.

UML diagrams

StackEdit enables you to write sequence diagrams and flow charts using a simple syntax.

write an md file

StackEdit can render musical scores using the ABC notation.

write an md file

StackEdit supports inserting emojis in your file using the Markdown emoji markup.

  • Trending Now
  • Data Structures
  • Foundational Courses
  • Data Science
  • Practice Problem
  • Machine Learning
  • Web Development
  • Web Browser
  • System Design
  • Software Development
  • Product Management

write an md file

  • Explore Our Geeks Community
  • Git Tutorial

Introduction to Git

  • Version Control Systems
  • Introduction and Installation of Git
  • History of Git
  • Git Features
  • Introduction to Github
  • What is a GIT Repository?
  • Bare Repositories in Git
  • What is Git-Ignore and How to Use it?

What is File?

  • What is GitHub README File and Markdown?
  • What is GitHub Labels?
  • Difference between CVS and GitHub

Git Installations

  • Git - SubGit
  • Git - Environment Setup
  • Using Git on CommandLine
  • Git- Setting up a Repository
  • Working with Git Repositories
  • Using GitHub with SSH (Secure Shell)
  • Working on Git for GUI
  • Difference Between Git and GitHub
  • States of a File in Git Working Directory
  • Use of Submodules in GitHub
  • How to Write Good Commit Messages in GitHub?
  • Deleting a Local GitHub Repository
  • Git Workflow Etiquettes
  • Git - Packfiles
  • Git - GC (Garbage Collection)
  • Git Flow vs Github Flow
  • Git - Difference Between HEAD, Working Tree and Index
  • Ignoring Files and Folders in Git

Git Commands

  • Basic Git Commands with Examples
  • Essential Git Commands
  • Top 12 Most Used Git Commands For Developers
  • Saving a file in Git
  • Difference between "add -A", "add -u", "add ." , and "add *"
  • Difference between “git add -A” and “git add”
  • Git- Debugging
  • How to Add Code on GitHub Repository?
  • Pushing changes to a Git Repository
  • Examining Git
  • Git-Checkout And Merge
  • Overturning Changes In Git
  • Submodules in Git
  • Git - Clean
  • Git - Rename
  • What is Git Init?
  • What is Git Add?
  • Committing in Git
  • Git - Origin Master
  • How to Set Upstream Branch on Git?
  • What is Git Push?
  • What is Git Pull?
  • Getting changes from a Git Repository
  • Git - Merge
  • Git | Working with Stash
  • Handling repositories with Git remote
  • Using Patches in Git
  • Patch Operation in Git
  • What is Git Clone?
  • Introduction to Git Aliases
  • Aliases in Git
  • Using Refs and Reflogs in Git
  • How to Undo a Commit in Git ?
  • Undoing in Git
  • Staging in Git
  • Git - Squash
  • Git - Move Files
  • Git - Status
  • How to Use git-blame?
  • Git - Index
  • Git - git-prune
  • Git Merge and Merge Conflict
  • Recovering Lost Commits in Git
  • Using Tags in Git
  • Git - Hooks
  • Git - Subtree
  • Git - Filtering the Commit History
  • Git - Cherry Pick
  • Git - git-show Command Line Utility
  • Git - Working Tree
  • Git - Changing History
  • Shallow Clone on Git in Linux
  • Sync your fork with master in GitHub
  • Error Searching and Handling in Git
  • Delete a Git Branch Locally and Remotely
  • How to Push Git Branch to Remote?
  • How to Add an Empty Directory to a Git Repository?
  • Difference Between Git Push Origin and Git Push Origin Master
  • Difference Between Git remote prune, Git prune and Git fetch --prune
  • Git - Difference Between Merging and Rebasing
  • How to Use Git Log to Format the Commit History?

Git and GitHub

  • How to Add Code of Conduct to Your Project on GitHub?
  • Difference Between fork and clone in GitHub
  • How to Add Audio Files on README .md File in a GitHub Repository From the Local System?
  • How to Add Videos on README .md File in a GitHub Repository?
  • How to Upload a Project on Github?
  • How to Export a Git Project?
  • How to Push a Project and Contribute on GitHub?
  • How to Push Anything to GitHub using Git Bash?
  • How to Push Folders From Local PC to GitHub using Git Commands?
  • How to Add Images on README .md File in a GitHub Repository From the Local System?
  • How to Transfer Local Repository to GitHub Organization?
  • How to Generate Personal Access Token in GitHub?
  • How to Add GIFs on README .md File in a GitHub Repository?
  • How to Change the Visibility of the GitHub Repository?
  • Issues in GitHub
  • Git - How to Solve "remote: Invalid username or password. fatal: Authentication failed"
  • Git - A lock file already exists in the repository, which blocks this operation from completing
  • Common Git Problems and Their Fixes
  • How to add a README to your GitHub profile?
  • How to Upload a Project through GitHub Desktop on GitHub
  • How to configure an OAuth App from GitHub?
  • How to move the most recent commit(s) to a new branch with Git
  • How to Use GIT with R and RStudio?
  • How to Use Git with Eclipse?
  • Git - Pack Objects
  • How to Add GIT Credentials in VSCode?

Git and GitHub in VS code

  • Creating a Pull Request on any Public Repository from GitHub using VS Code
  • How to Install GitHub Copilot on VSCode?
  • How to Upload Project on GitHub from Android Studio?
  • How to Clone Android Project from GitHub in Android Studio?

Git and GitHub in Android Studio

  • How to Create a Pull Request on GitHub using Android Studio?
  • How to Create a New Branch on Github using Pycharm?
  • Create a Pull Request on GitHub using Pycharm
  • How to Upload Project on GitHub from Pycharm?

Git and GitHub in Pycharm

  • How to deploy Node.js app on Heroku from GitHub ?
  • Deployment of React Application using GitHub Pages
  • How to Publish a Static Website on GitHub?
  • Using GitHub to host a free static website

Git and GitHub Deployment

  • How to Deploy Angular Application to Firebase using GitHub ?
  • How to Add Custom Domain To GitHub Pages?
  • How to Deploy a Django Application to Heroku with Git CLI?
  • How to create a CV using HTML and host in github ?
  • Deployment of Angular Application using Github Pages
  • How to Build Portfolio Website And Host It on GitHub Pages?
  • What is Collaboration in Git?
  • What are GitHub Collaborators?
  • What is GitHub Discussion?
  • Forking Workflow in Open Source Ecosystem
  • How to Clone Github Repository and Push Changes in Colaboratory?

Git and GitHub Collaboration

  • Merge Strategies in Git
  • Merge Conflicts and How to handle them
  • GitHub App to Add or Remove Labels to Issues
  • How to Create Pull Request on GitHub without Using any IDE?
  • How to Clone Web Project from GitHub in Pycharm using Git?
  • How to Clone a project from GitHub using Eclipse?
  • How to Export Eclipse projects to GitHub?
  • Creating New Branch on Github without using any IDE
  • How to Upload Project on GitHub from Jupyter Notebook?
  • How to Handle Big Repositories with Git?
  • How to Protect Your Private Email Addresses in Git & Github?
  • How to send Email using Git send-email via Gmail?
  • Dynamic Quote Generator for GitHub Readme
  • Automating some git commands with Python
  • How to Install and Use Git in Google Colab?

Advanced Git

  • Difference Between Bitbucket and GitHub
  • Using Bitbucket as an extension to GitHub capabilities
  • Working on BitBucket using Git
  • Introduction to Mercurial
  • Difference between MERCURIAL and GIT
  • Making a Github Bot
  • Jenkins and GIT Integration using SSH Key
  • GitHub App to Build Form using Typeform and Probot
  • How to Trigger WebHooks without Events - Probot Github App
  • Difference Between GitLab and GitHub
  • Difference Between GIT and SVN
  • Link your GitHub Account with R Studio
  • Continuous Integration and Continuous Development(CI/CD)
  • How to Add GIT Credentials in Jenkins?
  • Implementation of CI/CD in .NET application Using Shell Executor on GitLab
  • Implementation of CI/CD in Java application(Linux) Using Shell and Docker Executor on GitLab
  • Implementation of CI/CD in C/C++ Application(Linux) Using Shell and Docker Executor on GitLab
  • How to Publish Docker Image to Dockerhub Using Github Actions?
  • Installing Private Git Server on K8s Cluster with Gitea and AKS
  • Flutter - Building and Releasing APK using GitHub Actions
  • How to Upload Android APK to Testers Group in Firebase Using GitHub Actions?
  • Basic CI Workflow For Android using GitHub Actions
  • Github Actions For Android

A README file is an essential guide that gives other developers a detailed description of your GitHub project.

You may be wondering, Why anyone should spend time writing a README file. Well, here are some reasons to help convince you that it’s a good idea:

  • A good README helps your project to stand out from other projects and should be as good as your project itself.
  • It’s the first thing to notice while encountering your project, so it should be pretty brief but detailed.
  • The quality of a README description differentiates a good project from bad ones.
  • Many times is hosted as a website; make sure your webpage looks as cool as your project!

write an md file

Contents of Readme File:

The following are the general key components of a Readme file:

  • Include Your Project’s Title: This is the name of the project. It describes the whole project in few words and helps people understand the primary goal and aim.
  • Write a Description: Your description is an essential part of your project. A well-maintained description allows you to show off your work to other developers as well as potential employers.
  • How to Use Your Project: Provide instructions and examples so that users or contributors can use the project. This will make it easy for them so that if they encounter a problem, they will always have a place of reference.
  • Include Credits: If you have worked on the project as a team, list your team members. You should also include their GitHub profiles.

You can also add the following details in the Readme file:

  • What was your motivation? Why did you build this project?
  • What problem does the project solve? Or, what it does?
  • Why you used specific technologies? If your project has a lot of many features, list them here.
  • Mention some of the challenges you faced and features you hope to implement in the future.
  • Mention anything that you think you are proud of building or having in that project
  • What did you learn in the process?
  • What’s next for the project?
  • Mention languages, frameworks, databases, etc.
  • Provide deploy links or any other required links

Before diving deep into our project’s readme, let’s discuss markdown language.

  • Markdown is a lightweight markup language that allows us to style a digital text document using typical formatting techniques like headings, emphasis, lists, images, and links.
  • Markdown files have extensions .md or .markdown . We can convert Markdown into XHTML or HTML to display nicely in a browser.
  • Some of the many uses of Markdown are:
  • readme files
  • Writing messages in online discussion forums
  • Creating rich text using a plain text editor, emails, and technical documentation.
  • Popular sites that use Markdown include GitHub, Trello, Reddit, SourceForge, and StackExchange.
  • Markdown parsers also support dropping in blocks of HTML code that add to Markdown’s limited syntax if you want to achieve a more complex design.

Why should we use Markdown?

  • Easier for non-tech writers to produce documentation that can be both collaborative and flexible.
  • Easy to pick up – It has a base of email formatting conventions that most of us are exposed to already.
  • Easily readable (in its raw state), unlike HTML, which is full of tags.
  • Platform-independent – which means you can create Markdown files in any text editor.
  • Reusable skill : It’s versatile, and we can use it to take notes, create content for a website, or produce print-ready documents.

Now, let’s discuss elements of markdown language.

1. Headings:

  • Headings make your text more readable and help to break up the topics.
  • In Markdown, headings are formatted with hashes (#) in front of the line containing your heading.
  • You can use up to six hashes, with the number of hashes corresponding to a heading level.

Formatted text:

write an md file

2. Paragraphs:

  • To split your information up into paragraphs (with a noticeable gap between each paragraph).
  • Paragraphs are divided by a blank line (a line containing no characters) between consecutive paragraphs.

3. Line breaks:

  • To split your information up by inserting a new line with less space than you’d get from formatting as a paragraph. It is called a line break.
  • To insert a line break into your Markdown file, finish your line with at least two spaces and press return. It will render a new line for your text.

4. Italics:

  • Wrap the item with one star/underscore on each side.
  • Wrap the item with two stars/underscores on each side.

6. Simultaneously Bold and Italic:

  • Make your text Simultaneously bold and italic to give it even more weight!
  • Use three asterisks (or three underscores) to wrap your word or phrase.

7. Striking through:

  • Wrap the item in two tildes on each side.

write an md file

  • To link to external websites in Markdown content use two sets of brackets.
  • Wrap link text in brackets [ ], and then wrap the URL in parentheses ( ): [ ]( ).
  • Inserting an image into your Markdown file is similar to the formatting for links.
  • Begin your image formatting with an exclamation mark. Next, use square brackets to wrap your image alt text, next to parentheses containing the URL for your image.
  • Ensure there are no spaces between the exclamation mark, square brackets, or parentheses.
  • When your Markdown file renders to HTML, it will embed the image directly into the body text.

Formatted image:

write an md file

10. Unordered lists:

  • Markdown allows you to format your lists with several different symbols: asterisks (*), hyphens (-), or plus signs (+).
  • It’s up to you to choose which symbol you prefer. The result you get is the same.

write an md file

11. Ordered lists:

  • Format your ordered lists by preceding each list item with a number, followed by a full stop and then a space.
  • In Markdown, it doesn’t matter which numbers you use to format your list, as the list will always render as 1, 2, 3, and so on.

write an md file

12. Blockquotes:

  • Sometimes in Markdown, we will want to reference an external source using quotation marks. It is called a blockquote.
  • You represent any blockquote by preceding the first line of the block quote with a greater-than sign or angle bracket (>).

write an md file

13. Horizontal rules:

  • A horizontal rule is a tiny functional element that you can use to visually split up blocks of text within your Markdown file.
  • We represent a horizontal rule by three or more hyphens (-), asterisks (*), or underscores (_).

write an md file

14. Code snippets:

  • To reference snippets of code as examples, format code snippets using backticks ` that wrap your code snippet.
  • The first backtick “opens” the snippet, and the second backtick “closes” it.

write an md file

15. Code blocks:

  • Formatting code blocks is useful when you have a bigger chunk of code to include in your Markdown file.
  • Format your code blocks by indenting every line of your code block using one tab or four spaces.
  • And if you’d like to use syntax highlighting, including the language.

write an md file

16. Escaping:

  • In Markdown, you will often need to include characters in your text (for example, an asterisk) that may be part of the Markdown syntax.
  • You need to “escape” these characters, so your Markdown application doesn’t read these characters as formatting.
  • You escape characters in Markdown using a backslash before the character , with no space in between.

write an md file

17. Lists within a blockquote:

  • Nest your list formatting inside your blockquote formatting.
  • Format your blockquote using a greater-than sign (>) followed by a space, including a sign before every line of your blockquote.
  • Add your list formatting (*) just after your greater-than signs.

write an md file


  • Add a quotation with the > character at the beginning of each line.

write an md file

Since we are discussing , which is present in GitHub repositories, let’s discuss GitHub Flavored Markdown!

GitHub Flavored Markdown

  • uses its version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on
  • 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 Issues and Pull Requests.

1. Syntax highlighting:

  • Highlights the syntax.

write an md file

Formatted code:

write an md file

2. Task Lists:

  • To create a task list
  • 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.

write an md file

  • 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 (|).

write an md file

4.  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.

5. Automatic linking for URLs :

  • Any URL (like automatically converts into a clickable link.

6. Mathematical expressions :

  • You can also add math formula or equation with markdown.

Since now you know everything about r, the next time you make a repository don’t forget to add a perfect readme to your project!

Please Login to comment...

  • anikakapoor
  • pritam_sarbajna
  • Blogathon-2021

Please write us at contrib[email protected] to report any issue with the above content

Improve your Coding Skills with Practice



Because no one can read your mind ( yet )

What is it?

A README is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.

Why should I make it?

It's an easy way to answer questions that your audience will likely have regarding how to install and use your project and also how to collaborate with you.

Who should make it?

Anyone who is working on a programming project, especially if you want others to use it or contribute.

When should I make it?

Definitely before you show a project to other people or make it public. You might want to get into the habit of making it the first file you create in a new project.

Where should I put it?

In the top level directory of the project. This is where someone who is new to your project will start out. Code hosting services such as GitHub , Bitbucket , and GitLab will also look for your README and display it along with the list of files and directories in your project.

How should I make it?

While READMEs can be written in any text file format, the most common one that is used nowadays is Markdown . It allows you to add some lightweight formatting. You can learn more about it at the CommonMark website , which also has a helpful reference guide and an interactive tutorial .

Some other formats that you might see are plain text , reStructuredText (common in Python projects), and Textile .

You can use any text editor. There are plugins for many editors (e.g. Atom , Emacs , Sublime Text , Vim , and Visual Studio Code ) that allow you to preview Markdown while you are editing it.

You can also use a dedicated Markdown editor like Typora or an online one like StackEdit or Dillinger . You can even use the editable template below.

Markdown Input (editable)

Foobar is a Python library for dealing with word pluralization.


Use the package manager pip to install foobar.


Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Suggestions for a good README

Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.

Choose a self-explaining name for your project.


Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.

On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.

Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.

Within a particular ecosystem, there may be a common way of installing things, such as using Yarn , NuGet , or Homebrew . However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.

Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

If you have ideas for releases in the future, it is a good idea to list them in the README.

State if you are open to contributions and what your requirements are for accepting them.

For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

You can also document commands to lint the code or run tests . These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.

Authors and acknowledgment

Show your appreciation to those who have contributed to the project.

For open source projects, say how it is licensed .

Project status

If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.

Is there a standard README format?

Not all of the suggestions here will make sense for every project, so it's really up to the developers what information should be included in the README.

What are some other thoughts on writing READMEs?

Check out Awesome README for a list of more resources.

What should the README file be named? (or a different file extension if you choose to use a non-Markdown file format). It is traditionally uppercase so that it is more prominent, but it's not a big deal if you think it looks better lowercase .

What if I disagree with something, want to make a change, or have any other feedback?

Please don't hesitate to open an issue or pull request . You can also send me a message on Twitter .

Mind reading?

Scientists and companies like Facebook and Neuralink (presumably) are working on it. Perhaps in the future, you'll be able to attach a copy of your thoughts and/or consciousness to your projects. In the meantime, please make READMEs.

What's next?

More documentation.

A README is a crucial but basic way of documenting your project. While every project should at least have a README, more involved ones can also benefit from a wiki or a dedicated documentation website. GitHub , Bitbucket , and GitLab all support maintaining a wiki alongside your project, and here are some tools and services that can help you generate a documentation website:

  • Read the Docs

And to learn more about technical documentation in general, consider reading these books (I may earn commissions if you buy through these links):

  • Docs for Developers: An Engineer’s Field Guide to Technical Writing
  • Developing Quality Technical Information: A Handbook for Writers and Editors
  • Docs Like Code: Collaborate and Automate to Improve Technical Documentation
  • The Product is Docs: Writing Technical Documentation in a Product Development Group

If your project is open source , it's important to include a license . You can use this website to help you pick one.

Make a README is inspired by Keep a Changelog . A changelog is another file that is very useful for programming projects.

Just having a "Contributing" section in your README is a good start. Another approach is to split off your guidelines into their own file ( ). If you use GitHub and have this file, then anyone who creates an issue or opens a pull request will get a link to it.

You can also create an issue template and a pull request template . These files give your users and collaborators templates to fill in with the information that you'll need to properly respond. This helps to avoid situations like getting very vague issues. Both GitHub and GitLab will use the templates automatically.


  1. Riverside- Phnom Penh, Cambodia [Camp4th]

  2. Part 5

  3. 07 Files Versions

  4. Format file

  5. File Operation and file Attributes

  6. How to read and write file in UFI|| #UFI #software #flashing #viralreels #viral #reels #trending


  1. What Does “MD PA” Stand For?

    “MD PA” is an acronym. The most common meaning for this acronym is medical doctor, professional association. A professional association is an unincorporated business that is formed to provide necessary services to professionals.

  2. Top Tips for Finding Townhomes for Rent in Laurel, MD

    Are you looking for a townhome to rent in Laurel, MD? If so, you’re in luck. Laurel is a great place to live and there are plenty of townhomes available for rent. Here are some tips to help you find the perfect townhome for your needs.

  3. Get Ready to Make Your Move to Glen Burnie, MD

    Are you considering a move to the Baltimore area? If so, you should consider Glen Burnie, MD. Located just 10 miles north of Baltimore and 20 miles south of Annapolis, Glen Burnie is a great place to call home. Here are some reasons why you...

  4. Basic writing and formatting syntax

    Styling text. You can indicate emphasis with bold, italic, strikethrough, subscript, or superscript text in comment fields and .md files.

  5. How to write a file? (markdown file)

    For writing headings, you have to add hash # symbol at the beginning of the line. The number of the hash symbol will increase heading type will

  6. How to create a file?

    INSTRUCTIONS · Open any text editor or notepad. · Create a new file from — →file →new file. · Save the file as or any suitable name

  7. Getting Started

    How Does it Work? · Create a Markdown file using a text editor or a dedicated Markdown application. · Open the Markdown file in a Markdown application. · Use the

  8. How to Write a Good README File for Your GitHub Project

    What to Include in your README · 1. Project's Title · 2. Project Description · 3. Table of Contents (Optional) · 4. How to Install and Run the

  9. How to make a file? Easiest way!

    Comments3 · 3 Methods for Adding Images to GItHub README Files · 46. Git file. Learn how to write markdown syntax in the Readme file in

  10. How to write a file?

    To create a markdown file, name the file with the .md extension. For example, . Headings.

  11. Markdown and Files

    It would be much more time-efficient to write

  12. StackEdit

    StackEdit renders mathematics from LaTeX expressions inside your markdown file, as you would do on Stack Exchange. UML diagrams. StackEdit enables you to write

  13. What is File?

    Contents of Readme File: · Include Your Project's Title: This is the name of the project. · Write a Description: Your description is an essential

  14. Make a README

    While READMEs can be written in any text file format, the most common one that is used nowadays is Markdown. It allows you to add some lightweight formatting.