GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) — это улучшенная версия Markdown от GitHub с дополнительными функциями, разработанными специально для разработки программного обеспечения и совместной работы. Это руководство охватывает все специальные расширения синтаксиса, доступные на GitHub.

Что такое GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown расширяет базовый синтаксис Markdown функциями, которые делают его более полезным для:

Документации (READMEs, wikis)
Отслеживания задач (issues)
Pull requests
Рецензирования кода
Управления проектами

Основные функции GFM

1. Ограждённые блоки кода

GFM поддерживает ограждённые блоки кода с подсветкой синтаксиса для конкретных языков:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

javascript

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Подсветка синтаксиса

GitHub поддерживает подсветку синтаксиса для сотен языков. Некоторые распространённые из них:

bash

# Bash script
echo "Hello GitHub!"

python

# Python script
def greet(name):
    return f"Hello, {name}!"

java

// Java code
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Списки задач

Создавайте интерактивные списки задач с флажками:

markdown

- [x] Завершить аутентификацию пользователя
- [x] Реализовать API endpoints
- [ ] Написать модульные тесты
  - [ ] Тесты backend
  - [ ] Тесты frontend
- [ ] Развернуть в production

[x] Завершить аутентификацию пользователя
[x] Реализовать API endpoints
[ ] Написать модульные тесты
- [ ] Тесты backend
- [ ] Тесты frontend
[ ] Развернуть в production

4. Таблицы

GFM предоставляет простой синтаксис для создания таблиц:

markdown

| Функция           | Поддерживается | Описание                        |
|-------------------|----------------|---------------------------------|
| Ограждённый код   | ✅             | Подсветка для конкретного языка |
| Списки задач      | ✅             | Интерактивные флажки            |
| Таблицы           | ✅             | Структурированное отображение   |
| Упоминания        | ✅             | Уведомления пользователей       |
| Emoji             | ✅             | Визуальные выражения            |

Функция	Поддерживается	Описание
Ограждённый код	✅	Подсветка для конкретного языка
Списки задач	✅	Интерактивные флажки
Таблицы	✅	Структурированное отображение
Упоминания	✅	Уведомления пользователей
Emoji	✅	Визуальные выражения

5. Упоминания

Упоминайте пользователей или команды, чтобы уведомить их:

markdown

@username - Упомянуть конкретного пользователя
@team-name - Упомянуть команду

6. Emoji

Добавляйте emoji с помощью коротких кодов:

markdown

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Автоматическое создание ссылок

GFM автоматически создаёт ссылки для определённых типов контента:

Номера Issue и Pull Request

markdown

#123 - Ссылка на issue 123
PR #456 - Ссылка на pull request 456

Hash SHA

markdown

a1b2c3d - Ссылка на commit с этим SHA

Упоминания пользователей в Issues/PRs

markdown

@username - Автоматически ссылается на профиль пользователя

URLs

markdown

https://github.com - Автоматически становится ссылкой

8. Зачёркивание

GFM поддерживает зачёркнутый текст:

markdown

~~Этот текст зачёркнут~~

~~Этот текст зачёркнут~~

9. Ссылки на автолинки

GFM автоматически создаёт ссылки для:

HTTP/HTTPS URLs
Адресов электронной почты
Номеров issue/PR GitHub
Commit SHAs

markdown

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Подсветка строк в блоках кода

Подсвечивайте конкретные строки в блоках кода:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

javascript

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Подсветка синтаксиса Diff

Подсвечивайте изменения в коде с помощью синтаксиса diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

diff

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Специфическая разметка GitHub

Оповещения

Используйте специальный синтаксис для оповещений в документации GitHub:

markdown

> [!NOTE]
> Это оповещение типа note.

> [!TIP]
> Это оповещение типа tip.

> [!IMPORTANT]
> Это важное оповещение.

> [!WARNING]
> Это предупреждение.

> [!CAUTION]
> Это оповещение типа caution.

NOTE

Это оповещение типа note.

TIP

Это оповещение типа tip.

IMPORTANT

Это важное оповещение.

WARNING

Это предупреждение.

CAUTION

Это оповещение типа caution.

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

Используйте относительные ссылки для навигации между файлами в одном репозитории:

markdown

[README](/README.md)
[Руководство по внесению вклада](/CONTRIBUTING.md)
[Документация API](/docs/api.md)

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

markdown

![GitHub Logo](/images/github-logo.png "GitHub Logo - Текст при наведении")

Расширенное использование GFM

1. Вложенные списки со списками задач

Объединяйте вложенные списки со списками задач:

markdown

## Дорожная карта проекта

### Этап 1: Планирование
- [x] Определить область проекта
- [x] Выявить требования
  - [x] Функциональные требования
  - [x] Нефункциональные требования
- [x] Создать временную шкалу

### Этап 2: Разработка
- [x] Настроить структуру проекта
- [ ] Реализовать основные функции
  - [x] Аутентификация
  - [ ] Панель управления
  - [ ] Интеграция API

2. Таблицы с emoji и ссылками

Улучшайте таблицы с помощью emoji и ссылок:

markdown

| Компонент      | Статус            | Ответственный |
|----------------|-------------------|---------------|
| Аутентификация | ✅ Стабильно      | @johndoe      |
| База данных    | ⚠️ Требуется обновление | @janedoe |
| API            | 🚧 В процессе     | @bobsmith     |
| UI             | ✅ Стабильно      | @alicesmith   |

Компонент	Статус	Ответственный
Аутентификация	✅ Стабильно	@johndoe
База данных	⚠️ Требуется обновление	@janedoe
API	🚧 В процессе	@bobsmith
UI	✅ Стабильно	@alicesmith

3. Блоки кода в списках

Включайте блоки кода в списки:

markdown

1. Установите зависимости:

   ```bash
   npm install

Запустите сервер разработки:
bash
```
npm run dev
```
Соберите для production:
bash
```
npm run build
```


### 4. Блоки цитат с кодом

Объединяйте цитаты с блоками кода:

```markdown
> **Совет профессионала:** Используйте следующую команду для быстрой проверки статуса Git:
>
> ```bash
> git status
> ```

Совет профессионала: Используйте следующую команду для быстрой проверки статуса Git:
bash
git status

GFM в различных контекстах GitHub

Файлы README

Файлы README поддерживают все функции GFM и автоматически отображаются на страницах репозитория.

Issues и Pull Requests

Используйте списки задач для отслеживания прогресса
Упоминайте членов команды для совместной работы
Включайте фрагменты кода с подсветкой синтаксиса
Ссылайтесь на связанные issues/PRs с помощью синтаксиса #123

Wikis

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

Лучшие практики

1. Стиль кода

markdown

<!-- ✅ Хорошо -->
```javascript
// Используйте описательные имена функций
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

javascript

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Дизайн таблиц

markdown

<!-- ✅ Хорошо -->
| Функция | Описание | Статус |
|---------|----------|--------|
| Функция 1 | Краткое описание | ✅ |
| Функция 2 | Другое описание | 🚧 |

<!-- ❌ Избегайте -->
| Функция | Описание | Статус | | | |
|---------|----------|--------|---|---|---|
| Функция 1 | Это описание слишком длинное и делает таблицу трудной для чтения на мобильных устройствах | ✅ | | | |

3. Использование списков задач

markdown

<!-- ✅ Хорошо -->
## Sprint Backlog
- [x] Завершить страницу профиля пользователя
- [ ] Реализовать функционал поиска
  - [x] Backend API
  - [ ] Frontend компонент
- [ ] Написать документацию

<!-- ❌ Избегайте -->
- [ ] Задача 1
- [ ] Задача 2
- [ ] Задача 3
- [ ] Задача 4
- [ ] Задача 5
(Слишком много задач без организации)

GFM против стандартного Markdown

Функция	Стандартный Markdown	GitHub Flavored Markdown
Ограждённые блоки кода	❌	✅
Подсветка синтаксиса	❌	✅
Списки задач	❌	✅
Таблицы	❌	✅
Зачёркивание	❌	✅
Emoji	❌	✅
Упоминания	❌	✅
Автоматическое создание ссылок	Ограничено	Расширено

Инструменты для работы с GFM

Локальные редакторы

Visual Studio Code - Предварительный просмотр GFM и расширения
Typora - Рендеринг GFM в реальном времени
Mark Text - Поддержка GFM

Онлайн-инструменты

GitHub Gist - Создание и обмен фрагментами GFM
Dillinger - Онлайн-редактор GFM
StackEdit - Поддержка GFM с облачной синхронизацией

Инструменты командной строки

glow - Терминальный рендерер GFM
pandoc - Конвертация GFM в другие форматы
marked - Парсер GFM для Node.js

Распространённые проблемы и решения

1. Блок кода не подсвечивается

Проблема: Блок кода не отображает подсветку синтаксиса

Решение: Убедитесь, что вы указали правильный язык:

markdown

<!-- ✅ Правильно -->
```javascript
console.log("Hello");

jsx

console.log("Hello"); // Использование jsx вместо javascript для кода не JSX


### 2. Флажки списков задач не работают

**Проблема:** Флажки списков задач не интерактивны

**Решение:** Убедитесь в правильном синтаксисе (пробел между `-` и `[ ]`):

```markdown
<!-- ✅ Правильно -->
- [ ] Задача

<!-- ❌ Неправильно -->
-[ ] Задача (нет пробела)
-[x] Задача (нет пробела)

3. Таблица не отображается правильно

Проблема: Столбцы таблицы не выровнены

Решение: Убедитесь, что трубы правильно выровнены:

markdown

<!-- ✅ Правильно -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Неправильно -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Следующие шаги

GitHub Flavored Markdown — это мощный инструмент для общения и совместной работы в разработке программного обеспечения. Освоив эти функции, вы сможете создавать более эффективную документацию, лучше отслеживать задачи и более эффективно сотрудничать с вашей командой.

GitHub Flavored Markdown (GFM) ​

Что такое GitHub Flavored Markdown (GFM)? ​

Основные функции GFM ​

1. Ограждённые блоки кода ​

2. Подсветка синтаксиса ​

3. Списки задач ​

4. Таблицы ​

5. Упоминания ​

6. Emoji ​

7. Автоматическое создание ссылок ​

Номера Issue и Pull Request ​

Hash SHA ​

Упоминания пользователей в Issues/PRs ​

URLs ​

8. Зачёркивание ​

9. Ссылки на автолинки ​

10. Подсветка строк в блоках кода ​

11. Подсветка синтаксиса Diff ​

12. Специфическая разметка GitHub ​

Оповещения ​

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

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

Расширенное использование GFM ​

1. Вложенные списки со списками задач ​

2. Таблицы с emoji и ссылками ​

3. Блоки кода в списках ​

GFM в различных контекстах GitHub ​

Файлы README ​

Issues и Pull Requests ​

Комментарии ​

Wikis ​

Лучшие практики ​

1. Стиль кода ​

2. Дизайн таблиц ​

3. Использование списков задач ​

GFM против стандартного Markdown ​

Инструменты для работы с GFM ​

Локальные редакторы ​

Онлайн-инструменты ​

Инструменты командной строки ​

Распространённые проблемы и решения ​

1. Блок кода не подсвечивается ​

3. Таблица не отображается правильно ​

Следующие шаги ​

GitHub Flavored Markdown (GFM)

Что такое GitHub Flavored Markdown (GFM)?

Основные функции GFM

1. Ограждённые блоки кода

2. Подсветка синтаксиса

3. Списки задач

4. Таблицы

5. Упоминания

6. Emoji

7. Автоматическое создание ссылок

Номера Issue и Pull Request

Hash SHA

Упоминания пользователей в Issues/PRs

URLs

8. Зачёркивание

9. Ссылки на автолинки

10. Подсветка строк в блоках кода

11. Подсветка синтаксиса Diff

12. Специфическая разметка GitHub

Оповещения

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

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

Расширенное использование GFM

1. Вложенные списки со списками задач

2. Таблицы с emoji и ссылками

3. Блоки кода в списках

GFM в различных контекстах GitHub

Файлы README

Issues и Pull Requests

Комментарии

Wikis

Лучшие практики

1. Стиль кода

2. Дизайн таблиц

3. Использование списков задач

GFM против стандартного Markdown

Инструменты для работы с GFM

Локальные редакторы

Онлайн-инструменты

Инструменты командной строки

Распространённые проблемы и решения

1. Блок кода не подсвечивается

3. Таблица не отображается правильно

Следующие шаги