Быстрый старт для написания на GitHub

Изучите продвинутые функции форматирования, создав README для своего GitHub профиля.

Кто может использовать эту функцию?

Markdown можно использовать в веб-интерфейсе GitHub .

В этой статье

Введение

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

Если вы новичок в Markdown, возможно, стоит начать с курса AUTOTITLE или курса Общаться с помощью MarkdownGitHub Skills .

Если у вас уже есть профиль README, вы можете следовать этому руководству, добавив некоторые функции в существующий README или создав gist с файлом Markdown, который называется примерно таким about-me.md. Дополнительные сведения см. в разделе Создание gist.

Создание или изменение профиля README

Ваш профиль README позволяет делиться информацией о себе с сообществом на GitHub. ReadME отображается в верхней части страницы профиля.

Если у вас еще нет профиля README, его можно добавить.

  1. Создайте репозиторий с тем же именем, что и ваше GitHub имя пользователя, инициализируя репозиторий с README.md помощью файла. Дополнительные сведения см. в разделе Управление файлом сведений о профиле.
  2. Измените README.md файл и удалите текст шаблона (начало ### Hi there), который автоматически добавляется при создании файла.

Если у вас уже есть профиль README, его можно изменить на странице профиля.

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

  2. Щелкните рядом с профилем README.

    @octocatСнимок экрана: профиль README. Значок карандаша очертается темно-оранжевым цветом.

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

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

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

  1. Скопируйте и вставьте следующую разметку в README.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>

Как выглядит изображение

Снимок экрана: вкладка "Предварительная версия" комментария GitHub в светлом режиме. Изображение улыбающегося солнца заполняет коробку.

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

Таблицы 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       |

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

Снимок экрана: вкладка "Предварительный просмотр" комментария GitHub. Под заголовком "О мне" отображается таблица с рейтингом языков.

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

Чтобы сохранить содержимое в порядок, можно использовать <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

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

Снимок экрана: вкладка "Предварительный просмотр" комментария GitHub. Цитата отступлена ниже толстой горизонтальной линии.

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

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

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

    <!-- COMMENT -->

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

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

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

## About me

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

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

Когда вы довольны изменениями, сохраните профиль README, нажав кнопку "Зафиксировать изменения".

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

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