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

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

Заголовки

Чтобы создать заголовок, добавьте от одного до шести символов # перед его текстом. Количество используемых # элементов определяет уровень иерархии и размер шрифта заголовка.

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

При использовании двух или более заголовков GitHub автоматически создает оглавление, к которому можно получить доступ, щелкнув в заголовке файла. В оглавлении приводится каждый заголовок. Щелкнув по нему, можно перейти к соответствующему разделу.

Выделение текста

Текст в полях комментариев и файлах .md можно выделять полужирным шрифтом, курсивом, зачеркиванием, а также подстрочным или надстрочным шрифтом.

Текст в кавычках

Цитировать текст можно с помощью >.

Text that is not a quote

> Text that is a quote

Текст в кавычках имеет отступ с другим цветом типа.

Совет. Текст из беседы можно автоматически цитировать в комментарии. Для этого выделите текст и введите R. Чтобы процитировать весь комментарий, щелкните значок и выберите пункт Цитировать в ответе. Дополнительные сведения о сочетаниях клавиш см. в разделе сочетания клавиш.

Цитирование кода

Вы можете выделить код или команду в предложении с помощью одинарных грависов. Текст, заключенный в обратные кавычки, не форматируется. Кроме того, вы можете использовать сочетание клавиш COMMAND+E (Mac) или CTRL+E (Windows/Linux) для вставки обратных кавычек для блока кода в строке Markdown.

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

Чтобы выделить код или текст в отдельный блок, используйте тройные грависы.

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

Дополнительные сведения см. в разделе Создание и выделение блоков кода.

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

Поддерживаемые цветовые модели

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

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

Ниже указаны поддерживаемые сейчас цветовые модели.

Цвет	Синтаксис	Пример	Выходные данные
HEX	`#RRGGBB`	`#0969DA`
RGB	`rgb(R,G,B)`	`rgb(9, 105, 218)`
HSL	`hsl(H,S,L)`	`hsl(212, 92%, 45%)`

Ссылки

Чтобы создать встроенную ссылку, заключите ее текст в квадратные скобки [ ], а затем заключите URL-адрес в обычные скобки ( ). Чтобы создать ссылку, можно также использовать сочетание клавиш Команда+K . Выбрав текст, вы можете вставить URL-адрес из буфера обмена, чтобы автоматически создать ссылку из выделенного фрагмента.

Вы также можете создать гиперссылку Markdown, выделив текст и используя сочетание клавиш Command+V. Если вы хотите заменить текст ссылкой, используйте сочетание клавиш COMMAND+SHIFT+V.

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

Совет. GitHub автоматически создает ссылки при вводе допустимых URL-адресов в комментариях. Дополнительные сведения см. в разделе Автосвязанные ссылки и URL-адреса.

Ссылки на разделы

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

Относительные ссылки

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

Относительная ссылка — это ссылка, заданная относительно текущего файла. Например, если есть файл сведений в корне репозитория и еще один файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в файле сведений может выглядеть следующим образом:

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

GitHub автоматически преобразует относительную ссылку или путь к изображению с учетом текущей ветви, чтобы ссылка или путь всегда работали. Путь ссылки будет относительным к текущему файлу. Ссылки, начинающиеся с /, будут относительными к корневому каталогу репозитория. Можно использовать любые операнды относительных ссылок, например ./ и ../.

Относительные ссылки удобнее для пользователей, которые клонируют репозиторий. Абсолютные ссылки могут не работать в клонах репозитория. Мы рекомендуем использовать относительные ссылки на другие файлы в репозитории.

Изображения

Вы можете включить изображение, добавив ! и заключив замещающий текст в [ ]. Замещающий текст — это короткий текстовый эквивалент информации на изображении. Затем заключите ссылку на изображение в круглые скобки ().

![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 поддерживает внедрение изображений в проблемы, запросы на вытягивание, обсуждения, комментарии и файлы .md. Вы можете отобразить изображение из репозитория, добавить ссылку на изображение в Интернете или отправить изображение. Дополнительные сведения см. в разделе Отправка ресурсов.

Совет: Если вы хотите отобразить изображение, которое находится в репозитории, используйте относительные ссылки вместо абсолютных ссылок.

Ниже приведены некоторые примеры использования относительных ссылок для отображения изображений.

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

Дополнительные сведения см. в разделе Относительные ссылки.

Указание темы, в которой отображается изображение

Вы можете указать тему, для которой отображается изображение, в Markdown с помощью HTML-элемента <picture> в сочетании с функцией мультимедиа prefers-color-scheme. Имеется два цветовых режима: светлый и темный, поэтому доступны два варианта. Эти варианты можно использовать для отображения изображений, оптимизированных для темных или светлых фонов. Особенно полезно это в случае с прозрачными изображениями в формате PNG.

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

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

Старый метод указания изображений на основе темы с помощью фрагмента, добавленного к URL-адресу (#gh-dark-mode-only или #gh-light-mode-only), объявлен нерекомендуемым и будет заменен новым методом, который описан выше.

Списки

Вы можете создать неупорядоченный список, предваряя одну или несколько строк текста с -помощью , *или +.

- George Washington
* John Adams
+ Thomas Jefferson

Чтобы упорядочить список, поставьте перед каждой строкой номер.

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

Вложенные списки

Чтобы создать вложенный список, добавьте отступы для одного или нескольких элементов списка под другим элементом.

Чтобы создать вложенный список с помощью веб-редактора в GitHub или текстового редактора, использующего шрифт с монопространством, например Visual Studio Code, можно визуально выровнять список. Введите пробелы перед вложенным элементом списка, пока символ маркера списка (- или *) не будет расположен непосредственно под первым символом текста в элементе над ним.

1. First list item
   - First nested list item
     - Second nested list item

Примечание. В веб-редакторе можно добавить или убрать отступы для одной или нескольких строк текста, сначала выделив нужные строки, а затем нажав клавиши TAB или SHIFT+TAB соответственно.

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

В этом примере можно добавить элемент вложенного списка под элементом 100. First list item списка, отступив от начала строки не менее чем на пять пробелов, так как перед текстом First list item пять символов (100 .).

100. First list item
     - First nested list item

Таким же образом можно создавать несколько уровней вложения списков. Например, так как первый элемент вложенного списка содержит семь символов (␣␣␣␣␣-␣) перед содержимым First nested list itemвложенного списка, необходимо навести отступ для второго элемента вложенного списка по крайней мере еще на два символа (не менее девяти пробелов).

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

Дополнительные примеры см. в спецификации GitHub Flavored Markdown.

Списки задач

Чтобы создать список задач, добавьте к элементам списка префикс — дефис, пробел, а затем [ ]. Чтобы пометить задачу как завершенную, используйте [x].

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

Если описание элемента списка задач начинается с круглой скобки, необходимо экранировать ее с помощью символа :

- [ ] (Optional) Open a followup issue

Дополнительные сведения см. в разделе Сведения о списках задач.

Упоминание людей и команд

Вы можете упомянуть пользователя или команду на GitHub, введя @ перед их именем. Пользователь или команда получит уведомление, которое привлечет их внимание к беседе. Пользователи также получают уведомления, когда вы изменяете комментарий, упоминая имя пользователя или команды. Дополнительные сведения об уведомлениях см. в разделе Об уведомлениях.

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

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

Когда вы упоминаете родительскую команду, члены дочерних команд также получают уведомления, что упрощает взаимодействие с несколькими группами людей. Дополнительные сведения см. в разделе Сведения о командах.

При вводе символа @ отображается список людей или команд, участвующих в проекте. Список фильтруется по мере ввода, поэтому после того, как вы найдете имя нужного человека или команды, можно выбрать его с помощью клавиш со стрелками и нажать клавишу TAB или ВВОД, чтобы завершить имя. Для команд введите @organization/team-name, и все члены этой команды будут подписаны на беседу.

Результаты автозавершения ограничены участниками репозитория и любыми другими участниками беседы.

Ссылка на проблемы и запросы на вытягивание

Вы можете получить список предлагаемых проблем и запросов на вытягивание в репозитории, введя #. Введите номер или заголовок проблемы либо запроса на вытягивание, чтобы отфильтровать список, а затем нажмите клавишу TAB или ВВОД, чтобы завершить выделенный результат.

Дополнительные сведения см. в разделе Автосвязанные ссылки и URL-адреса.

Ссылка на внешние ресурсы

Если для репозитория настроены пользовательские автоматические ссылки, то ссылки на внешние ресурсы, такие как проблема JIRA или тикет Zendesk, конвертируются в сокращенные ссылки. Чтобы узнать, какие автоматические ссылки доступны в репозитории, обратитесь к кому-то, у кого есть разрешения администратора в отношении репозитория. Дополнительные сведения см. в разделе Настройка автоматической привязки для отсылок на внешние ресурсы.

Отправка ресурсов

Вы можете отправлять такие ресурсы, как изображения, путем перетаскивания, выбора в обозревателе файлов или вставки. Вы можете отправлять ресурсы в проблемы, запросы на вытягивание, комментарии и файлы .md в репозитории.

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

Вы можете добавить эмодзи к тексту, введя :EMOJICODE:двоеточие, за которым следует имя эмодзи.

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

При вводе : отображается список предлагаемых эмодзи. Список фильтруется по мере ввода, поэтому после того, как вы найдете нужный эмодзи, нажмите клавишу TAB или ВВОД, чтобы завершить выделенный результат.

Полный список доступных эмодзи и кодов см . в разделе Эмодзи-Памятка.

Абзацы

Чтобы создать абзац, оставьте пустую строку между строками текста.

Вы можете добавлять в содержимое сноски с помощью квадратных скобок, используя следующий синтаксис:

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.

Сноски отрисовываются следующим образом:

Скрытие содержимого с помощью комментариев

Вы можете сообщить GitHub, что необходимо скрыть содержимое в отрисованном файле Markdown, поместив это содержимое в комментарий HTML.

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

Игнорирование форматирования Markdown

Вы можете сообщить GitHub, что необходимо игнорировать (или экранировать) форматирование Markdown, используя символ перед символом Markdown.

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

Дополнительные сведения о обратных косых чертах см. в разделе «Синтаксис Markdown» Daring Fireball.

Примечание. Форматирование Markdown не будет игнорироваться в названии проблемы или запросе на вытягивание.

Отключение отрисовки Markdown

При просмотре файла Markdown можно щелкнуть в верхней части файла, чтобы отключить обработку файлов Markdown и просмотреть источник файла.

Отключение обработки файлов Markdown позволяет использовать функции просмотра источника, такие как связывание строк, что невозможно при просмотре обработанных файлов Markdown.

Дополнительные материалы

• Спецификация GitHub Flavored Markdown
• «Сведения о написании и форматировании текста на GitHub»
• «Работа с расширенным форматированием»
• «Краткое руководство по написанию на GitHub»

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

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

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

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

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

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

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/