Краткое руководство по написанию на GitHub

Введение

Markdown — это удобный в читаемом и написании язык для форматирования обычного текста. Вы можете использовать синтаксис Markdown вместе с некоторыми дополнительными html-тегами для форматирования записи в GitHub, в таких местах, как репозиторий READMEs и комментарии о запросах на вытягивание и проблемах. В этом руководстве описаны некоторые расширенные функции форматирования, создав gist.

Если вы не знакомы с Markdown, вам может потребоваться начать с курса "Базовый синтаксис записи и форматирования" или курса "Обмен данными с помощью Markdown GitHub Skills.

Создание gist

Gists позволяет хранить фрагменты кода и другие фрагменты информации или делиться ими с другими пользователями в ваше предприятие. Чтобы использовать функции форматирования в gists, добавьте gist-файл с расширением .md .

1. Перейдите на домашняя страница gist, http(s)://gist.[hostname].
2. При необходимости введите описание для gist, например "Обо мне".
3. В поле Имя файла, включая расширение... , введите about-me.md.

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

Добавление изображения в соответствии с вашими посетителями

Изображения можно включать в GitHub. Здесь вы добавите адаптивное изображение, например баннер, в начало gist.

С помощью элемента HTML <picture> с prefers-color-scheme функцией мультимедиа можно добавить изображение, которое изменяется в зависимости от того, использует ли посетитель светлый или темный режим. Дополнительные сведения см. в разделе Управление параметрами темы.

1. Скопируйте и вставьте следующую разметку в файл about-me.md.

   HTML

   <picture>
    <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE">
    <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE">
    <img alt="YOUR-ALT-TEXT" src="YOUR-DEFAULT-IMAGE">
   </picture>

2. Замените заполнители в разметке URL-адресами выбранных изображений. Кроме того, чтобы сначала опробовать эту функцию, можно скопировать URL-адреса из приведенного ниже примера.

   • Замените YOUR-DARKMODE-IMAGE URL-адресом изображения, отображаемого для посетителей в темном режиме.
   • Замените YOUR-LIGHTMODE-IMAGE URL-адресом изображения, отображаемого для посетителей в светлом режиме.
   • Замените YOUR-DEFAULT-IMAGE URL-адресом изображения, отображаемого в случае, если другие изображения не могут быть сопоставлены, например, если посетитель использует браузер, который не поддерживает эту функцию prefers-color-scheme .

3. Чтобы сделать изображение доступным для посетителей, использующих средство чтения с экрана, замените YOUR-ALT-TEXT его описанием.

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

Дополнительные сведения об использовании изображений в Markdown см. в разделе Базовый синтаксис записи и форматирования.

Пример адаптивного изображения

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

Внешний вид изображения

Добавление таблицы

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

1. Вернитесь на вкладку Изменить новый файл .

2. Чтобы представиться, две строки под тегом </picture> , добавьте заголовок ## About me и короткий абзац о себе, как показано ниже.

   ## About me
   
   Hi, I'm Mona. You might recognize me as GitHub's mascot.
   

3. В двух строках под этим абзацем вставьте таблицу путем копирования и вставки следующей разметки.

   Markdown

   | Rank | THING-TO-RANK |
   |-----:|---------------|
   |     1|               |
   |     2|               |
   |     3|               |

4. В столбце справа замените THING-TO-RANK словом "Языки", "Хобби" или другими словами и заполните столбец своим списком вещей.

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

Дополнительные сведения см. в разделе Организация информации с помощью таблиц.

Пример таблицы

## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

| Rank | Languages |
|-----:|-----------|
|     1| Javascript|
|     2| Python    |
|     3| SQL       |

Внешний вид таблицы

Добавление свернутого раздела

Чтобы поддерживать порядок содержимого, можно использовать <details> тег для создания разворачиваемого свернутого раздела.

1. Чтобы создать свернутый раздел для созданной таблицы, заключите таблицу в <details> теги, как показано в следующем примере.

   HTML

   <details>
   <summary>My top THINGS-TO-RANK</summary>
   
   YOUR TABLE
   
   </details>

2. Между тегами замените <summary> THINGS-TO-RANK на все, что вы ранжированы в таблице.

3. При необходимости, чтобы по умолчанию раздел отображался как открытый open , добавьте атрибут в <details> тег .

   <details open>
   

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

Пример свернутого раздела

<details>
<summary>My top languages</summary>

| Rank | Languages |
|-----:|-----------|
|     1| Javascript|
|     2| Python    |
|     3| SQL       |

</details>

Как выглядит свернутый раздел

Добавление цитаты

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

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

   ---
   

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

   > QUOTE
   

   Замените QUOTE цитатой по своему усмотрению. Кроме того, можно скопировать цитату из приведенного ниже примера.

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

Пример цитаты

---
> If we pull together and commit ourselves, then we can push through anything.

— Mona the Octocat

Как выглядит цитата

Добавление комментария

Вы можете использовать синтаксис комментариев HTML, чтобы добавить комментарий, который будет скрыт в выходных данных. Здесь вы добавите комментарий, чтобы напомнить себе об обновлении gist позже.

1. В двух строках ## About me под заголовком вставьте комментарий с помощью следующей разметки.

   <!-- COMMENT -->
   

   Замените COMMENT элементом to-do, который вы напоминаете себе о необходимости выполнить что-то позже (например, чтобы добавить дополнительные элементы в таблицу).

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

Пример комментария

## About me

<!-- TO DO: add more details about me later -->

Сохранение работы

Когда вы будете довольны изменениями, сохраните gist.

• Чтобы сохранить gist скрытым от поисковых систем, но видимым для всех, кому вы предоставляете URL-адрес, щелкните Создать секрет gist.
• Если вы рады, что ваш gist был виден всем пользователям в ваше предприятие, щелкните Создать внутренний gist.

Дальнейшие действия

• Ознакомьтесь с дополнительными функциями форматирования. Например, см. "Создание и выделение блоков кода".
• Используйте новые навыки при общении в GitHub, в вопросах, запросах на вытягивание и обсуждениях. Дополнительные сведения см. в разделе Взаимодействие с GitHub.