How to write readme md

Как написать красивый и информативный README.md

Многие программисты лихо управляются с кодом и знают мельчайшие подробности своих проектов. Но некоторым из них (в том числе и мне) недостаёт коммуникативных навыков.

Удивительное дело: программист может потратить час на подгонку внутренних и внешних отступов для одной-единственной кнопки и не найти каких-то 15 минут на файл Readme описания проекта.

Надеюсь, вы уже знаете, что такое файл readme.md и для чего он нужен. На всякий случай попробую объяснить.

Что такое Readme.md?

README (буквально означает «прочти меня») — это первый файл, который нужно читать, получив доступ к проекту на Github или любой Git-хостинговой площадке. Этот файл в первую очередь и предлагается вниманию пользователя, когда он открывает здесь репозиторий того или иного проекта. Такой файл содержит кучу полезной информации, так что его вполне можно рассматривать как справочное руководство по проекту.

Посмотрите, где у нас здесь файл Readme:

Файл Readme.md находится в корневой папке репозитория и автоматически отображается в каталоге проекта на github.

Вот как выглядит файл разметки на github (здесь использован VSCode, который одновременно показывает нам файлы разметки и в режиме предварительного просмотра):

Здесь можно найти официальный гайд Github для формата разметки на тот случай, если вам захочется основательно разобраться в языке разметки.

Зачем тратить время на Readme?

Генерирование документации для ваших компонентов

How to write readme md

Copy raw contents

Copy raw contents

Описание разметки файла README.md

получается разделительная черта

Заголовок первого уровня

Заголовок первого уровня также можно создать:

Заголовок второго уровня

Заголовок второго уровня также можно создать:

Заголовок третьего уровня

Заголовок четвертого уровня

Заголовок пятого уровня

Заголовок шестого уровня

Работа с выделением текста

Зачеркнутый текст (Strikethrough)

Для выделения текста жирным или наклонным и их сочетания можно использовать комбинации * или _

Жирный текст (bold)

Наклонный текст (italic)

Жирный наклонный текст (bold italic)

Жирный текст (bold)

Наклонный текст (italic)

Жирный наклонный текст (bold italic)

Тут странный текст

Использование эмодзи (emoji)

В самом тексте можно использовать эмодзи, например написать вот так:
✅ Это уже сделано
❎ Я не буду это делать
🔲 делать или не делать, вот в чем вопрос?
В оригинале это выглядит так (в конце строки четыре (4) пробела для того, что бы был переход на новую строку):

Использование цитирования в тексте

Внешний вид, конечно, не очень, но может и пригодиться.

Если нужно выделить слово или фразу внутри строки, то используются одинарные обратные кавычки (`):

Дополнительно можно задавать язык кода внутри блока, указав его после первых трех кавычек:

Пример блока для C# :

Пример блока для Python :

Можно создавать многоуровневые списки. Каждый уровень отделяется четырьмя (4) пробелами:

Каждый уровень отделяется двумя пробелами.

Для Githib работа с нумерованными списками выглядит очень интересно. Каждый уровень отделяется четырьмя (4) пробелами:

При использовании смешанных списков нужно очень внимательно следить за нумерацией. Лучше, как и в нумерованных, использовать четыре (4) пробела для отделения уровня.

Также можно создавать многоуровневые списки задач. Каждый уровень отделяется четырьмя (4) пробелами:

Либо просто вставить ссылку, либо дополнительно задать текст ссылки (пробела между скобками быть не должно):

Второй вариант записывается так: [текст ссылки](адрес ссылки)

Вставка ссылки с картинкой на ролик с YouTube

Описание комбинации [](ссылка на страничку YouTube)
Пример:
[](https://youtu.be/RHPYGwVQB2o)
Что мы увидим:

How to write a good README for your GitHub project?

Get to know why writing a good README is important, and how to improve its legibility.

What is a README file?

README (as the name suggests: «read me») is the first file one should read when starting a new project. It’s a set of useful information about a project, and a kind of manual. A README text file appears in many various places and refers not only to programming. We will focus on a programmer’s README, though.

example of README for a Bootstrap gem (Ruby On Rails)

Added README file on GitHub appears under the list of files in a repository.

If we work professionally or learn coding, many times we come across the public repositories. We use the libraries made available by other developers as an open source code or we make our contribution to a project, reporting/fixing bugs, and adding new functionalities. Certainly, we use these projects because they just come in handy, and offer a high quality solution. But would we use them if they lacked a user-friendly description, that is, a good README?

What’s the use of writing a good README?

I am just learning so why should I be bothered about adding a README file? That code is just for me, after all, not for the whole community.

I doubt the code is just for you. And adding a README file is a good move.

README for Junior Devs

OK, now let’s check why we should care for our README files since the first project!

For a budding programmer, GitHub is a calling card. The projects on GitHub are most often our portfolio. When we’re at a career stage without a considerable commercial experience or nice-looking non-profit projects, a presentation of our achievements in a form of repositories is one of the best way to get visible to the recruiters. A preparation of several demonstration projects we want to show off during the interview works the best.

If we are just learning and we drop our training projects there, let’s pay attention to their good description. Even a non-technical recruiter will be able to recognize the technologies we touched, and check if it goes in line with a candidate’s profile he’s/she’s looking for.

In Polish or in English?

Certainly, in English. Add a project description in English even if your project is in Polish language. The projects realized at the university might be treated as an exeption as they often demand a documentation in Polish. In every other case, describe your projects in English.

.md extension comes from a word: markdown. It’s a markup language for text formatting. Maybe at first it isn’t be obvious but markup has been created to make text creation easier. In HTML language, the most important heading goes with h1 tag. Similarily, we will have # before a heading in our document.

You’ll find out more on markdown usage on GitHub, and on dillinger.io you’ll find an editor with a preview.

Open a README.md. file in a new project.

Make sure the file always includes the following elements:

Consider also using additional elements such as:

That’s a lot! There’s not so much to say about my project!

Titles and internal titles

Introduction

Introduction is like a summary. It shouldn’t be too long as we don’t want to read an essay on a project. We should describe in an interesting manner what’s the project aim, and what problems does a given application solve. Two or three sentences are enough in case of a small project.

If it’s a training project, mention your incentive. Why did you want to create it? To learn a particular technology? Was it a hackathon project? Was it for a non-profit organization? Is it an application created to memorize the material from workshops or and online course? It’s worth mentioning here, without a doubt.

Technologies

Let’s write down the languages we used, the libraries and its versions.
For example:

Why? Firstly, it will be helpful when launching the project in the future. The versions of libraries change, and an inconspicuous change might cause many problems later on. It’s good to know the version that has been used when our code was working exactly the way we wanted.

Another thing: recruitment. IT recruiters browse through their candidates’ GitHub accounts. Even though they lack a technical knowledge to estimate the quality of solutions, they know the keywords related to their job offers. A description of used technologies might make you stand out among other candidates.

Let’s assume there’s a multitude of candidates for an internship, and a recruitment time is limited. CVs have been selected, there are two similar candidates, and a last available date in a calendar. The candidates’ GitHub accounts include the same number of projects. One of them mentions the technologies in every project. A second candidate doesn’t add README files or his/her projects are described poorly. What do you think, which candidate will be invited for an interview?

Launch

How to run a project? Does a project has minimum hardware requirements?

We mentioned the libraries and their versions earlier. If necessary, technologies, launch, and hardware requirements can be merged together. But if we split it into two subsections, it’s worth to focus here specifically on launching a project. When we have a website or application, it can concerned setting up a local environment, a link to GitHub pages or deployed application on Heroku. Do we need input data? If so, in what format?

Let’s focus on other elements that can improve our README.

Table of contents

Table of contents comes in handy in case of extensive documentation. It can work as a simple list with the links to headings.

And it will look like:

Illustrations

Example: In my README file, I want to place a block schema that would illustrate how an algorithm works. I keep my schema.jpg file in a directory called images. To display it in my documentation, I will use a code:

Scope of functionalities

There’s no always use in describing the scope of functionalities. For a website-visiting card or a simple application of to-do type, the list of functionalities is an excess of form.

On the other hand, a seemingly simple project such as to-do list can be extended with many interesting options we can be proud of: users register, recording and classifying the tasks according to date, adding commentaries to the tasks or data export to the files.

Examples of use

In case of reusable code or your own library, providing a manual how to use our project might be necessary. It can work as a fragment of code:

which will be displayed as:

The project status

Sources

Should we add information when our project was based on a tutorial or we got inspired with a given task? Yes, sure.

If our code was based on somebody else’s code, we should add such information.

When our code was only inspired by another solution/an application, you can mention it and write the way you got inspired, what changes you made, what functionalities were developed.

When we solve the sets of exercises, it’s worth adding where others can find their description. If we will want to come back to these sources, the link will come up easily. This way, the author who shared his/her knowledge is, spent his/her time to prepare and share this material is also respected.

Other information

A good, legible README

The suggestions above are mine. The most importaint point is just legibility. A thorough documentation make your repository shine in front of the recruiters and other programmers. There are many approaches to writing a good README. Take a look at the following examples:

How to write a readme.md file? (markdown file)

In this article, you can learn what is a markdown file and how to write the markdown file. Most of the times you can find this file in the remote repository.

What is readme.md file?

It is a simple plain text file that contains the basic information of the files and some guides. It is used to write some installation guide or basic documentation inside the project directory. Most popular repository providers like GitHub, gitlab and bitbucket are using the readme.md file as a file descriptor.

What is markdown?

Markdown is a scripting language that is very lightweight. It is used to format plain text to a respective design. Markdowns are rapidly used in content writing in some blog post web sites. It converts some plain text to the desired format in HTML. The simplicity and easy to understand is making the markdown more popular. It takes all the text from the markdown file and converts to HTML through a markdown app or a compiler.

If you are a beginner to markdown file then this article is for you. I am going to write a readme.md file so that you will have a better understanding of the markdown script.

Here I am using visual studio code IDE for writing markdown file. Below are the steps to create a markdown file in visual studio code.

Step-1: Open visual studio code and goto file > new file

Step-2: Name the file as readme.md or readme.markdown and save the file.

Step-3: Find and click the ‘open preview to the side’ icon.

Step-4: Start writing the script.

Headings

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 change according to that.

You can write up to Heading 6.

Normal text

If you want to write normal text then write simple text here, no need to add any tags it will automatically convert into text.

Hyperlinks

You can add a hyperlink in a markdown file by using the below tag.

You can also write link title (While hovering over the link the title will appear)

(targetURL «Link title»)

e.g. [Github](https://www.github.com «Github home»)

note: Make sure a single space should be their between targetURL and title)

Strong and italic text

You can write strong and italic text by appending underscores _ before and ending of the line, for italic text add double star ** before and ending of the line for strong/bold text.

_Italic text here_

StrikeThrough

If you want to strike through a word or line then add two tilde symbol at the beginning and end of the line.

Images

You can add images in a markdown file by using the below tag.

Tables

You can write a table by using the below format of text.

Quotes

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

>Your quote looks like this.

You can write code by appending ` symbol at the beginning and end of the line.

Code block

If you want to write a block of code then add «` at starting and ending of the code.

You can specify your language after the «` at starting of the line.

You can write an ordered list, unordered list, and mixed list. Please see the below format how to write a list.

Horizontal line

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 size of the heading.

When you use two or more headings, GitHub automatically generates a table of contents which 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.

This was mistaken text

, then Quote reply. For more information about keyboard shortcuts, see «Keyboard shortcuts.»

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.

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

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 «Enabling fixed-width fonts in the editor.»

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.

Here are the currently supported color models.

Color	Syntax	Example	Output
HEX	`#RRGGBB`	`#0969DA`
RGB	`rgb(R,G,B)`	`rgb(9, 105, 218)`
HSL	`hsl(H,S,L)`	`hsl(212, 92%, 45%)`

Notes:

This site was built using [GitHub Pages](https://pages.github.com/).

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

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

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/CONTRIBUTING.md, the relative link to CONTRIBUTING.md in your README might look like this:


Tip: When you want to display an image which is in your repository, you should 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 which 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

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.

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

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

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.

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.

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?

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

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

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, check out 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:

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.

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\*.

For more information, see Daring Fireball’s «Markdown Syntax.»

Disabling Markdown rendering

When viewing a Markdown file, you can click

at the top of the file to disable Markdown rendering and view the file’s source instead.

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

Help us make these docs great!

All GitHub docs are open source. See something that’s wrong or unclear? Submit a pull request.