Использование содержимого

Сведения о содержимом GitHub Docs

Наше содержимое применяет правила руководства по стилю в содержимом Markdown.

Linter используется markdownlint в качестве платформы для выполнения проверок, отчетов о недостатках и автоматическом исправлении содержимого по возможности. Эта платформа гибко выполняет определенные правила, предоставляет описательные сообщения об ошибках и устраняет ошибки. Содержимое GitHub Docs использует несколько существующих markdownlint правил и дополнительных настраиваемых правил для проверки содержимого Markdown в наших content и data каталогах. Наши пользовательские правила реализуют проверки, которые пока недоступны в markdownlint платформе или относятся к содержимому GitHub Docs. Правила проверяют синтаксис для Markdown и Liquid.

Выполнение содержимого GitHub Docs

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

Автоматический запуск linter при предварительной фиксации

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

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

При локальном написании содержимого существует несколько правил, которые можно исправить автоматически с помощью командной строки. Если вы хотите автоматически исправить ошибки, которые можно исправить, см. статью "Автоматическое исправление ошибок, которые можно исправить".

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

Запуск linter вручную

Запуск linter на поэтапном и измененном файлах

Используйте следующую команду, чтобы локально запустить linter на промежуточных и измененных файлах. Это приведет к error выводу и warning недостатков серьезности.

npm run lint-content

Запуск linter на поэтапном и измененном файлах и только сообщения об ошибках

Используйте следующую команду, чтобы локально запустить linter на этапе и измененных файлах, а также сообщить о недостатках только error серьезности.

npm run lint-content -- --errors

Запуск linter для определенных файлов или каталогов

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

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

Автоматическое исправление ошибок, которые можно исправить

Если в описании ошибки fixable: true вы можете использовать следующие команды для автоматического исправления.

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

npm run lint-content -- --fix

Выполните следующую команду, чтобы исправить определенные файлы или каталоги:

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

Запуск определенного набора правил linter

Используйте следующую команду для выполнения одного или нескольких конкретных правил linter. В этих примерах выполняются heading-increment правила и code-fence-line-length правила. Замените heading-increment code-fence-line-length одним или несколькими псевдонимами linter, которые вы хотите запустить. Чтобы просмотреть список правил linter, которые можно передать этому параметру, выполните команду npm run lint-content -- --help. Можно использовать короткое имя (например, MD001) или длинное имя (например, heading-increment) правила linter.

Запустите указанные правила linter во всех промежуточных и измененных файлах:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

Выполните указанные правила linter для определенных файлов или каталогов:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

Обход перехватчика фиксации

Если ошибка linter catchs, которую вы не ввели, можно обойти перехватчик фиксации Git с помощью --no-verify параметра при фиксации изменений.

git commit -m 'MESSAGE' --no-verify

Отображение меню справки для скрипта содержимого linter

npm run lint-content -- --help

Правила подстраивание

Каждое правило настроено в файле, src/content-linter/styleгде определены серьезность правил.

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

Синтаксис правил подкладки

Некоторые правила подстроки возвращают предупреждения или ошибки на основе html-комментариев, которые можно добавить в статьи.

Синтаксис для истечения срока действия и истечения срока действия содержимого

Правила GHD038 и GHD039 проверка содержимого, заданного вручную датой окончания срока действия. За 19 дней до указанной даты содержимое будет возвращено предупреждение о том, что срок действия содержимого истекает в ближайшее время. Начиная с указанной даты содержимое возвращает ошибку и помечает содержимое для исправления.

Вы можете добавить дату окончания срока действия в содержимое, упаковав его в HTML-теги, содержащие дату окончания срока действия в формате: <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

Используйте:

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

Обратите внимание, что если вы помещаете истекшие теги в HTML-элемент table , убедитесь, что тег проходит по всей строке и не только ячейке. Например:

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label has been deprecated and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

Подавление правил linter

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

Например, если вы пишете статью, содержащую регулярное выражение (^|/)[Cc]+odespace/ , которое проверяет синтаксис обратной ссылки, оно активирует MD011 правило, которое проверяет обратные ссылки. Вы можете отключить правило MD011 в этой конкретной строке, добавив следующий комментарий.

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

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

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

Эти комментарии можно использовать для включения или отключения правил.