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

Сведения о содержимом 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 is закрытие 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 -->

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