Инструкция по работе с git markdown

Создавайте расширенное форматирование текста и кода в GitHub с помощью простого синтаксиса.

Headings

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.

# A first-level heading
## A second-level heading
### A third-level heading

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.

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

Text that is not a quote

> Text that is a quote

Quoted text is indented, with a different type color.

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.

Use `git status` to list all new or modified files that haven't yet been committed.

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

Some basic Git commands are:
```
git status
git add
git commit
```

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.

The background color is `#ffffff` for light mode and `#000000` for dark mode.

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%)`

Links

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](https://pages.github.com/).

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 .

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

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

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.

Images

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.](https://myoctocat.com/assets/images/base-octocat.svg)

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:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

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.

Lists

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

- George Washington
* John Adams
+ Thomas Jefferson

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

1. James Madison
1. James Monroe
1. John Quincy Adams

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.

1. First list item
   - First nested list item
     - Second nested list 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.

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.

100. First list item
     - First nested list item

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

100. First list item
       - First nested list item
         - Second nested list item

For more examples, see the GitHub Flavored Markdown Spec.

Task lists

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

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

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

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:

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.

Paragraphs

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:

Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
  This is a second line.

The footnote will render like this:

Alerts

Note: The Markdown syntax used during the beta testing period is now deprecated and will be removed. You can use the syntax as described in this section.

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.

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

Three types of alert 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.

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

Here are the rendered alerts.

Hiding content with comments

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

<!-- This content will not appear in the rendered Markdown -->

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

Further reading

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

Время на прочтение
7 мин

Количество просмотров 29K

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

Изложенный здесь подход, с примером конкретной реализации, имеет низкий порог вхождения. Технически, уже завтра вы можете начать работать по-новому.

Постановка задачи

Вам нужно создать некий документ или набор документов. Возможно, это проектная документация или протоколирование вашей сети, или что-то более простое, например, вы должны описать процессы в компании или в вашем отделе. В общем, речь идет о любом документе или наборе документов с текстом, картинками, табличками… Усложним задачу тем, что

1. данная работа предполагает совместный труд, усилия группы или нескольких групп сотрудников
2. на выходе вы хотите иметь документ в определенном формате, с атрибутами корпоративного стиля, созданный по определенному шаблону. Для определенности мы будем считать, что это MS Word (.docx)

10 лет назад подход был бы однозначным: мы бы создали MS Word документ или документы и каким-либо образом организовали бы работу по изменению.

И такой подход по-прежнему в силе. Им пользуются в том числе и крупные интеграторы при создании проектной документации. Но интуитивно понятно, что, если вы действительно интенсивно, со многими правками и обсуждениями, в течении продолжительного времени работаете над документом данный подход не очень удобен.

Пример

Я довольно остро ощутил эту проблему, работая в одном крупном интеграторе. Процесс изменения проектной документации был следующий:

1. инженер скачивает последнюю версию MS Word (.docx) документа
2. меняет название
3. вносит правки в track моде
4. отсылает документ с правками архитектору
5. так же отсылает перечень всех исправлений с комментариями
6. архитектор анализирует изменения
7. если все хорошо, то копирует данные изменения в файл с последней версией, меняет версию, выкладывает на общий ресурс
8. если есть замечания, то инициируется обсуждение (email или митинги)
9. достигается консенсус
10. далее пункты 3 — 9

Пока работа не была интенсивной, то это кое-как, но все же работало. Но в определенный момент этот процесс стал узким местом целого проекта и привел к проблемам. Дело в том, что все становится плохо, как только изменения производятся часто и одновременно несколькими командами.

Так, когда мы перешли на стадию предварительного тестирования, то начали проявляться разные проблемки и, хотя и по мелочам, но нужно было часто менять документацию — четыре разные команды, ежедневно, практически одновременно, с обсуждениями. Все эти изменения проходили через одного инженера — архитектора. Файл с дизайном проекта был огромный, и как следствие, архитектор был завален рутинной работой, связанной с большим количеством копирования, редактирования, делал много ошибок, приходилось все перепроверять, перепосылать, и в общем это было близко к хаосу.

В данном случае этот подход, подход работы над документом MS Word, работал с большим скрипом и создавал проблемы.

Git, Markdown

Столкнувшись с проблемой, описанной в примере выше, я стал исследовать этот вопрос.
Я увидел, что все более становится популярным использование Markdown совместно с Git при создании документов.

Git — это инструмент для разработки. Но почему бы его не использовать для процесса документирования? В этом случае вопрос многопользовательской работы становится решенным. Но для того, чтобы в полной мере использовать возможности Git нам нужен текстовый формат документа, нам нужно найти другой инструмент, не MS Word, и для этих целей отлично подходит Markdown.

Markdown — простой язык текстовой разметки. Он предназначен для создания красиво оформленных текстов в обычных файлах формата TXT. Если мы будем создавать наши документы в Markdown, то связка Markdown — Git выглядит естественной.

И все бы хорошо, и в этом месте можно было бы поставить точку, если бы не наше второе условие: «на выходе нам нужен документ в определенном формате, с атрибутами корпоративного стиля, созданный по определенному шаблону» (и мы договорились вначале, что для определенности это будет MS Word). То есть, если мы решили использовать Markdown, то нам нужно как-то преобразовать этот файл в .docx требуемого вида.

Существуют программы конвертации между различными форматами, например, Pandoc.
Вы можете конвертировать Markdown файл в .docx формат с этой программой.
Но все же, надо понимать, что, во-первых, не все, что есть в Markdown будет конвертировано в MS Word и, во-вторых, MS Word — это целая страна по сравнению со стройным, но все же городком, Markdown. Есть огромное количество всего, что есть в Word и ни в каком виде нет в Markdown. Нельзя просто так вот взять и с определенными ключами Pandoc конвертировать ваш Markdown формат в желанный вид MS Word. Так что обычно, после конвертации, приходится «дорабатывать» полученный .docx документ вручную, что опять-таки может быть затратным с точки зрения времени и приводить к ошибкам.

Если бы мы могли написать скрипт, который автоматически «доделывал» бы то, с чем не справился Pandoc — это было бы идеальное решение.

В силу не тождественности функционала MS Word и Markdown в общем виде решить эту задачу, думаю, невозможно, но можно ли это сделать применительно к конкретным ситуациям, конкретным требованиям? Мой опыт показал, что да, можно и скорее всего это возможно для многих, или может быть даже большинства ситуаций.

Решение частной задачи

Так, в моем случае, после конвертации файла с помощью Pandoc, мне приходилось вручную делать дополнительную обработку файлов, а именно

• добавлять в Word поля с автоматической нумерацией заголовков (caption) таблиц и картинок
• менять стиль для таблиц

Я не нашел, как это сделать стандартными (Pandoc) или известными средствами. Поэтому я применил python скрипт с pywin32 пакетом. В результате я получил полную автоматизацию. Теперь я могу конвертировать мой Markdown файл в нужную форму MS Word документа одной командой.

Смотрите детали здесь.

Замечание

В этом примере я, конечно же, преобразую некий абстрактный Markdown файл, но в точности тот же подход был применен к «боевому» документу, и на выходе я получил практически точно тот же MS Word документ, который до этого мы получали ручным форматированием.

В общем, c pywin32 мы получаем практически полный контроль над MS Word документом, что позволяет менять его, и приводить к виду, который требует ваш корпоративный стандарт. Конечно, этих же целей можно было добиться и с использование других инструментов, например, VBA макросов, но мне было удобней использовать python.

Краткая формула данного подхода:

Markdown + Git -- (нечто) --> MS Word

Не так важно, чем является «нечто». В моем случае это был Pandoc и python с pywin32. Возможно, у вас другие предпочтения, но важно то, что это возможно. И это и есть главный посыл этой статьи.

Резюмируя, идея в том, что при таком подходе вы работаете только с Markdown файлом и пользуетесь Git для организации совместной работы и для контроля версий, и только при необходимости (например, чтобы предоставить документацию клиенту) автоматически создаете файл нужного формата (например, MS Word).

Процесс

Думаю, для многих формула, приведенная выше достаточна, чтобы понять, как теперь может быть организован процесс работы с документацией. Но все же я обычно ориентируюсь на сетевых инженеров, поэтому в общих чертах покажу, как теперь может выглядеть процесс работы, и чем это отличается от подхода с редактированием MS Word файлов.

Для определенности, в качестве платформы для работы с Git выберем GitHub. Тогда вы должны создать репозиторий и в master ветке поместить Markdown файл или файлы, с которыми планируете работать.

Мы рассмотрим простой процесс, основанный на «github flow». Его описание можно найти, как в интернете, так и на хабре.

Предположим, что над документацией работают четыре человека и вы — один из них. Тогда создаются четыре дополнительные ветки (branch), например, с именами этих людей. Каждый работает локально, в своей ветке и делает изменения со всеми необходимыми git командами.

Выполнив какой-то законченный кусок работы, вы формируете pull request, инициируя таким образом обсуждение ваших изменений. Возможно, в процессе обсуждения, выяснится, что вы должны добавить или изменить что-то еще. В этом случае, вы делаете необходимые изменения и создаете дополнительный pull request. В конце концов, ваши изменения принимаются и сливаются (merge) с master веткой (или отвергаются).

Конечно, это довольно общее описание. Предлагаю для создания детализированного процесса обратиться к вашим разработчикам или найти знающих людей. Но хочу заметить, что порог вхождения в Git довольно низкий. Это не говорит о том, что протокол простой, но вы можете начать с простого. Если вы совсем ничего не знаете, думаю, потратив несколько часов или может быть дней на изучение и установку, вы можете начать им пользоваться.

Какая же польза в данном подходе по сравнению, например, с процессом, описанном в примере выше?

На самом деле процессы довольно схожи, просто вы заменили

копирование файла -> создание ветки (branch)
копирование текста в конечный файл-> слияние (merge)
копирование последних изменений к себе -> git pull/fetch
обсуждение в переписке -> pull requests
track mode -> git diff
последняя утвержденная версия -> master ветка
бэкап (копирование на удаленный сервер) -> git push
…

Таким образом вы автоматизировали все то, что вам и так приходилось делать, но вручную.

На более высоком уровне это позволяет вам

• создать ясный, простой и контролируемый процесс изменений документации
• т.к. конечный документ (в нашем примере MS Word) вы создаете автоматически, то это уменьшает вероятность ошибок, связанных с форматированием

Замечание

В силу сказанного выше, думаю очевидно, что, даже если вы работаете над документацией один, то использование Git может существенно облегчить вашу работу

Все это повышает качество документации и уменьшает время на ее создание. И еще небольшой бонус — вы изучите Git, что поможет вам при автоматизации вашей сети

Как перейти на новый процесс?

В начале статьи я написал, что уже завтра вы можете начать работать по-новому. Как перевести вашу работу в новое русло?

Вот последовательность шагов, которую вам скорее всего придется выполнить:

• если ваш документ очень большой, разбейте его на части
• конвертируйте каждую часть в Markdown (с помощью Pandoc, например)
• установите один из редакторов Markdown (я пользуюсь Typora)
• скорее всего вам придется подправить форматирование созданных Markdown документов
• начинайте применять процесс, описанный в предыдущей главе
• параллельно начинайте видоизменять скрипт конвертации под свою задачу (или создайте что-то свое)

Вам не обязательно ждать, когда вы создадите и отладите в совершенстве механизм конвертации Markdwon -> требуемый на выходе вид документа. Дело в том, что, даже если вам не удастся быстро полностью автоматизировать процедуру преобразования ваших Markdown файлов, вы все равно сможете это сделать в каком-либо виде с помощью Pandoc и далее довести до конечного вида вручную. Обычно вам не нужно это делать часто, а только в конце определенных этапов, и эта ручная работа, хоть и неудобна, но все же, на мой взгляд, вполне допустима на этапе отладки и не должна сильно «тормозить» процесс.

Все остальное (Markdown, Git, Pandoc, Typora) уже готово и не требует особых усилий или времени для того, чтобы начать работать с ними.

Getting started with writing and formatting on Github

You can use simple features to format your comments and interact with others in issues, pull requests, and wikis on GitHub.

About writing and formatting on Github

GitHub combines a syntax for formatting text called GitHub Flavored Markdown with a few unique writing features.

Markdown is an easy-to-read, easy-to-write syntax for formatting plain text.

We’ve added some custom functionality to create GitHub Flavored Markdown, used to format prose and code across our site.

You can also interact with other users in pull requests, issues, and wikis with features like @mentions, issue and PR references, and emoji.

Text formatting toobar

Every comment field on GitHub contains a text formatting toolbar, allowing you to format your text without learning Markdown syntax. In addition to Markdown formatting like bold and italic styles and creating headers, links, and lists, the toolbar includes GitHub-specific features such as @mentions, task lists, and links to issues and pull requests.

Further reading

• “Basic writing and formatting syntax”
• “Working with advanced formatting”
• “Mastering Markdown”
• “Markdown Tutorial”

Basic writing and formatting syntax

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

Headings

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.

# The largest heading
## The second largest heading
###### The smallest heading

Styling text

You can indicate emphasis with bold, italic, or strikethrough text.

Quoting text

You can quote text with a >.

In the words of Abraham Lincoln:
> Pardon my French

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.

Use `git status` to list all new or modified files that haven't yet been committed.

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

	Some basic Git commands are:
	```
	git status
	git add
	git commit
	```

For more information, see “Creating and highlighting code blocks.”

Links

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.

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

Lists

You can make a list by preceding one or more lines of text with - or *.

- George Washington
- John Adams
- Thomas Jefferson

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

1. James Madison
2. James Monroe
3. John Quincy Adams

Rendered ordered list

You can create nested lists by indenting lines by two spaces.

1. Make my changes
  1. Fix bug
  2. Improve formatting
    * Make the headings bigger
2. Push my commits to GitHub
3. Open a pull request
  * Describe my changes
  * Mention all the members of my team
    * Ask for feedback

Task lists

You can create task lists by prefacing list items with [ ]. To mark a task as complete, use [x].

Task lists render with checkboxes in all comments and Markdown files. Select or unselect the checkboxes to mark them as complete or incomplete.

- [x] Finish my changes
- [ ] Push my commits to GitHub
- [ ] Open a pull request

You can reorder task lists by clicking to the left of a task’s checkbox, dragging it to a new location, and dropping it. If you have multiple lists within a comment, you can reorder tasks across them. You can’t add or reorder tasks in other comments.

Mentioning users and teams

You can mention a user or team on GitHub by typing @ plus their username or team name to bring their attention to an issue or pull request.

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

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 hit either tab or enter to complete the name. For teams, just enter the @organization/team-name and all members of that team will get subscribed to the issue.

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 PR number or title to filter the list, then hit either tab or enter to complete the highlighted result.

For more information, see “Autolinked references and URLs.”

Using emoji

You can add emoji to your writing by typing :EMOJICODE:.

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

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 emoji-cheat-sheet.com.

Paragraphs and line breaks

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

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

Further reading

• “About writing and formatting on GitHub”
• “Working with advanced formatting”
• “Mastering Markdown”
• “Markdown Tutorial”

Working with advanced formatting

Formatting like tables, syntax highlighting, and automatic linking allows you to arrange complex information clearly in your pull requests, issues, and comments.

Organizing information with tables

You can build tables to organize information in comments, issues, pull requests, and wikis.

Creating a table

You can create tables with pipes | and hyphens -. Hyphens are used to create each column’s header, while pipes separate each column.

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

The pipes on either end of the table are optional.

Cells can vary in width and do not need to be perfectly aligned within columns. There must be at least three hyphens in each column of the header row.

| Command | Description |
| --- | --- |
| git status | List all new or modified files |
| git diff | Show file differences that haven't been staged |

Formatting content within your table

You can use formatting such as links, inline code blocks, and text styling within your table:

| Command | Description |
| --- | --- |
| `git status` | List all *new or modified* files |
| `git diff` | Show file differences that **haven't been** staged |

You can align text to the left, right, or center of a column by including colons : to the left, right, or on both sides of the hyphens within the header row.

| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| git status   | git status     | git status    |
| git diff     | git diff       | git diff      |

To include a pipe | as content within your cell, use a \ before the pipe:

| Name     | Character |
| ---      | ---       |
| Backtick | `         |
| Pipe     | \|        |

Further reading

• “Basic writing and formatting syntax”

Creating and highlighting code blocks

Share samples of code with fenced code blocks and enabling syntax highlighting.

Fenced code blocks

You can create fenced code blocks by placing triple backticks «« before and after the code block. We recommend placing a blank line before and after code blocks to make the raw formatting easier to read.

	```
	function test() {
	  console.log("notice the blank line before this function?");
	}
	```

Syntax highlighting

You can add an optional language identifier to enable syntax highlighting in your fenced code block.

For example, to syntax highlight Ruby code:

	```ruby
	require 'redcarpet'
	markdown = Redcarpet.new("Hello World!")
	puts markdown.to_html
	```

We use Linguist to perform language detection and syntax highlighting. You can find out which keywords are valid in the languages YAML file.

Further reading

• “Basic writing and formatting syntax”

Autolinked references URLs

References to URLs, issues, pull requests, and commits are automatically shortened and converted into links.

URLs

GitHub automatically creates links from standard URLs.

For more information on creating links, see “Basic writing and formatting syntax.”

Issues and pull requests

Within repositories, references to issues and pull requests are automatically converted to shortened links to the issue or pull request.

Commit SHAs

References to a commit’s SHA hash are automatically converted into shortened links to the commit on GitHub.

To save time and make sure you’re delivering a consistent message, you can add saved replies to issue and pull request comments.

Once you’ve added a saved reply, it can be used in both issues and pull requests. Saved replies are tied to your user account. Once they’re created, you’ll be able to use them across repositories and organizations.

Creating a saved reply

If you frequently add the same comment over and over, you can create a saved reply.

Changing a saved reply

If you have a saved reply that has an error or isn’t saying exactly what you’d like, you can make it more useful by changing it.

Deleting a saved reply

If you find that you’re no longer using a saved reply, you can delete it.

When commenting on an issue or pull request, you can add a saved reply that you’ve already set up. The saved reply can be the entire comment or if you want to customize it, you can add or delete content.

View the original page: https://help.github.com/categories/writing-on-github/

Hail, fellow Git pilgrims! As we wind down our tutorial series on learning Git and GitHub from your first git init to your most recent pull request, we now pause to consider the humble, often overlooked, README.md file.

What is a README.md, exactly, in GitHub land? When you visit any repository on GitHub, the first thing you see is the file tree — which, for massive open source projects like the Linux kernel, can be dozens of lines long. Directly below the list of project files is where you find the README.

The README is like the public face of your work. It’s the first way most people who come to your repo will interface with your project, and it’s so important that GitHub includes README creation prompts in the repository setup workflow:

Too many developers, however, either skip the README entirely, or put some generic boilerplate text in. We’ve all done it, every one of us with the intent to come back later and do it right. Which happens approximately never. This is understandable; software development is a fast-flowing river, and it’s super hard to paddle back upstream to revisit any code that is not a problem/bug/actively on fire. That doesn’t mean it’s good, though. In fact, it’s really bad to skimp on your README.

How bad? Well, Tom Preston-Werner, one of the founders of GitHub, wrote a compelling essay about README Driven Development: “The Readme should be the single most important document in your codebase; writing it first is the proper thing to do…

First. As in, before you write any code or tests or behaviors or stories or ANYTHING. I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong. Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding.

So. Don’t be That Guy who clearly works really really hard creating an open source project, puts it up on GitHub with no README whatsoever… and then sits there wondering why nobody is forking their project. Or even looking at it. Because, um, you failed to tell us what it even IS?

Writing a Great README

What, then, are the elements of a great README?

Every one of the 27 million public repositories on GitHub represents a project, from entire JavaScript frameworks to tiny single-function software packages somebody, somewhere, thought might be useful. So there is no one set way of writing a README that works for all repos. On the other hand, every single one starts the same way: WHAT YOUR PROJECT DOES.

(Seriously. If you are having trouble getting started writing a README, here is a sentence prompt: “My project is…”.  Now fill in the rest by telling us about This Thing I Made, ‘k?)

Here is a list of what a typical README will contain:

1. What your project does
2. How to install it
3. Example usage

After that, you might consider including some of these other helpful sections:

1. How to set up the dev environment
2. A FAQ
3. Changelog
4. License and author info

Using Markdown to Make Your README Look Professional

So above is the info you need to include. Here is a guide to (1) how you might maybe format it and (2) how to do that formatting with GitHub Flavored Markdown. This is a GitHub-specific markdown language, as in a lightweight text-based syntax for formatting text. Plainly put, it’s a bunch of hash signs and other symbols you use with text to make things bigger or bolder or otherwise change their appearance. Think of it as styles file for a webpage, only without the pesky HTML and CSS.

Markdown works on GitHub with any file that has .md or .markdown extensions. Like, README.md. You can also use it to create colorful pull request comments, and even in commit messages. You can even include emojis!

If you’ve never used markdown before, don’t be intimidated. It’s dead simple. You simply create a README.md file, open it in your fave text editor and start typing. Remember: the text, what you’re saying about your project, is the important part. Don’t get too caught up in styling. (That said, a stylish-looking README will only be an asset, so do have some fun with it).

First Step: Project Title and Description.

How we worked this markdown magic:

# Project Title An overview of **what** your project does/is about goes here ### Motivation :rocket: —————— A short description of the reason you made this project — **why** it exists.

Markdown is so basic: you just type in your desired text, then tell it what to do by attaching certain symbols to it. If you want a blank line, you insert one blank line — or more, if you want bigger blank space — in between two lines of text.

1. The hashtag controls text size:

# This is the largest title font size (think <h1> tag in HTML) ## This is a bit smaller, for sub-headings (like <h2> tag) ###### This is as small as it gets before regular text.

Since your project title should probably big, you write it out as “# My Project Title” (the space between the beginning markdown symbol, here a hashtag, and the first letter of the title is important).

1. . Typing a row of em dashes ( – – – – -) will draw a solid divider line on screen.
2.  Want to emphasize text? Use the asterisk symbol. “ **I am bold!** “ will generate I am bold!, while “*I am oblique!” produces I am oblique!
3. Emojis are easy: check out the emoji cheat sheet. (Pro tip: if you use Slack, you’re already familiar — it’s the same markdown library).  Pick your emoji, then type the name between two semicolons: “:rocket:” produces the rocketship symbol lots of people like to include in initial commit messages, for example.

Add Links, Code Samples and Screenshots.

Other README content that jazzes up the appearance of your project’s repository landing page while simultaneously providing valuable user information:

• Links to other resources, like APIs.
• Code samples
• Screenshots/images

So our next section, Technical Information — where you include information about the tools you used to build your project — looks like this. Note the hypertext link to Atom:

Markdown:

### Technical information —————— Shoutout — with links — to the framework, libraries or anything else that went into building your opus: **Built with** [Atom](https://github.com/atom)

Again, we are using hashtags and asterisks to create title-sized and bold text effects, and a row of dashes to create a line.

The markdown for inserting an external link is “ [Link text here](https://url goes here)” So, the text you want to serve as your link anchor goes inside two brackets [ ], immediately followed — no space in between — by ( ) parentheses containing the url.

Once more, Slack users will already know how to do this: enclose inline code snippets in single backticks and code blocks in triple backticks. Markdown will take care of the formatting:

«`javascript function fancyAlert(arg) {  if(arg) {    $.facebox({div:‘#foo’})  } } «`

Ideally you would have an equally compelling screenshot of your brilliant open source software/library/npm module to draw interest to your project. A voracious giant robot centipede worm works, too.

The markup is nearly identical to inserting a hyperlink, so be careful. The main difference is that an image/screenshot is prefaced with a ! bang symbol:

### Screenshots/Images —————— A picture is worth a thousand words. 

Note how the [ ] brackets and ( ) parentheses syntax is otherwise identical. You can use a link to an externally hosted image, or an internal path to assets hosted on your project repo.

That’s It. Really.

Well, not really really. There are a few other markdown toys to play with, but these are the essentials for putting together a simple but effective, attractive-looking README on your GitHub repository.

See? Markdown can be fun!  Be careful to not get overly caught up in the code at the cost of good content. Just remember: the words really are the most important part.

Feature image via Pixabay.

Group
Created with Sketch.