Skip to main content

Эта версия GitHub Enterprise Server была прекращена 2024-03-26. Исправления выпускаться не будут даже при критических проблемах безопасности. Для повышения производительности, повышения безопасности и новых функций выполните обновление до последней версии GitHub Enterprise Server. Чтобы получить справку по обновлению, обратитесь в службу поддержки GitHub Enterprise.

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

Содержимое можно использовать для проверка ваших вкладов для ошибок.

Сведения о содержимом 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 в определенных файлах или каталогах. Разделите несколько путей с пробелом. Файлы и каталоги можно включить в одну и ту же команду.

Shell
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 ветвь. Большинство правил в конечном итоге будут повышены до ошибок, так как содержимое больше не имеет предупреждений нарушений.

Идентификатор правилаИмена правилDescriptionСерьезностьТеги
MD001приращение заголовка, увеличение заголовкаУровни заголовков должны увеличиваться только на один уровень за разerrorзаголовки, заголовки
MD002first-header-h1, first-header-h1Первый заголовок должен быть заголовком верхнего уровняerrorзаголовки, заголовки
MD004ul-styleСтиль неупорядоченного спискаerrorмаркер, ul
MD009no-trailing-spacesКонечные пробелыerrorпробел
MD011no-reversed-linksСинтаксис обратной ссылкиerrorссылки
MD012без нескольких пустыхНесколько последовательных пустых строкerrorпробелы, blank_lines
MD014commands-show-outputЗнаки доллара, используемые перед командами без отображения выходных данныхerrorкодом
MD018no-missing-space-atxНет места после хэш-заголовка стиля atxerrorзаголовки, заголовки, atx, пробелы
MD019no-multiple-space-atxНесколько пробелов после хэш-заголовка стиля atxerrorзаголовки, заголовки, atx, пробелы
MD022пустые заголовки, пустые вокруг заголовковЗаголовки должны быть окружены пустыми строкамиerrorзаголовки, заголовки, blank_lines
MD023header-start-left, header-start-leftЗаголовки должны начинаться в начале строки.errorзаголовки, заголовки, пробелы
MD027no-multiple-space-blockquoteНесколько пробелов после символа blockquoteerrorblockquote, пробелы, отступы
MD029ol-префиксПрефикс упорядоченного элемента спискаerrorol
MD030list-marker-spaceПробелы после маркеров спискаerrorol, ul, пробелы
MD031пустые заборы вокругБлоки заборированного кода должны быть окружены пустыми строкамиerrorкод, blank_lines
MD037без пробела в акцентеПробелы внутри маркеров выделенияerrorпробелы, акцент
MD039no-space-in-linksПробелы внутри текста ссылкиerrorпробелы, ссылки
MD040забортный язык кодаБлоки кода, защищенные, должны иметь указанный языкerrorкод, язык
MD042no-empty-linksНет пустых ссылокerrorссылки
MD047single-trailing-newlineФайлы должны заканчиваться одним символом новой строкиerrorblank_lines
MD049стиль акцентаСтиль выделения должен быть согласованнымerroremphasis
MD050сильный стильСтрогий стиль должен быть согласованнымerroremphasis
search-replaceзаполнитель todocs-placeholderПерехват вхождения заполнителя TODOCS.error
search-replacedocs-domainПерехват вхождения домена docs.gitub.com.error
search-replaceдомен справкиПерехват вхождения домена help.github.com.error
search-replaceПредварительная версия доменаПерехват вхождения домена preview.ghdocs.com.error
search-replaceдомен разработчикаПерехват вхождения домена developer.github.com.error
search-replaceустаревший синтаксис жидкости: site.dataПерехват вхождений устаревшего синтаксиса данных жидкости.error
search-replaceустаревший синтаксис жидкости: octicon-Используемый синтаксис октикона жидкости не рекомендуется. Вместо этого используйте этот формат octicon "<octicon-name>" aria-label="<Octicon aria label>"error
GH001no-default-alt-textИзображения должны иметь значимый альтернативный текст (замещающий текст)errorспециальные возможности, изображения
GH002no-generic-link-textИзбегайте использования универсального текста ссылки, например Learn more или Click hereerrorспециальные возможности, ссылки
GHD030длина строки забора кодаЛинии ограждения кода не должны превышать максимальную длинупредупреждений (не рекомендуется)код, специальные возможности
GHD032image-alt-text-end-punctuationАльтернативный текст для изображений должен заканчиваться знаками препинанияerrorспециальные возможности, изображения
GHD004image-file-kebab-caseИмена файлов изображений должны использовать kebab-caseerrorimages
GHD033неверный alt-text-lengthЗамещающий текст изображений должен составлять от 40 до 150 символовпредупреждений (не рекомендуется)специальные возможности, изображения
GHD002internal-links-no-langВнутренние ссылки не должны иметь жестко закодированный языковой кодerrorссылки, URL-адрес
GHD003внутренняя косая чертаВнутренние ссылки должны начинаться с /errorссылки, URL-адрес
GHD031image-alt-text-exclude-wordsАльтернативный текст для изображений не должен начинаться с таких слов, как "изображение" или "графический"errorспециальные возможности, изображения
GHD034list-first-word-capitalizationПервое слово элемента списка должно быть заглавнопредупреждений (не рекомендуется)ul, ol
GHD001препинание ссылокЗаголовки внутренних ссылок не должны содержать знаки препинанияerrorссылки, URL-адрес
GHD008ранние ссылки на accessФайлы, которые не являются ранним доступом, не должны ссылаться на файлы с ранним доступом или ранним доступомerrorфункция, ранний доступ
GHD021задания yaml-scheduled-jobsФрагменты YAML, включающие запланированные рабочие процессы, не должны выполняться в час и должны быть уникальнымиerrorфункция, действия
GHD006внутренняя версия-links-old-versionВнутренние ссылки не должны иметь жестко закодированную версию с использованием старого синтаксиса управления версиямиerrorссылки, URL-адрес, управление версиями
GHD005hardcoded-data-variableСтроки, содержащие "личный маркер доступа", должны использовать переменную продукта.errorодин источник
GHD013github-owned-action-referencesСсылки на действия, принадлежащие GitHub, не должны быть жестко закодированыerrorфункция, действия
GHD016liquid-quoted-условно-argУсловные теги Liquid не должны кавычки условного аргументаerrorжидкость, формат
GHD014liquid-data-references-definedСсылки на ликвидные или отступные данные найдены в содержимом, не имеющих значения или не существующих в каталоге данных.errorliquid
GHD015формат liquid-data-tagТеги ссылок на данные liquid или indented должны иметь правильное количество аргументов и интерваловerrorжидкость, формат
GHD010frontmatter-hidden-docsСтатьи с свойством hidden frontmatter могут находиться только в определенных продуктахerrorfrontmatter, компонент, ранний доступ
GHD009frontmatter-early-access-referencesФайлы, которые не являются ранним доступом, не должны иметь интерфейсные элементы, ссылающиеся на ранний доступerrorfrontmatter, компонент, ранний доступ
GHD011frontmatter-video-transcriptsРасшифровка видео должна быть настроена правильноerrorfrontmatter, feature, video-transcripts
GHD012frontmatter-schemaFrontmatter должен соответствовать схемеerrorfrontmatter, схема
GHD007заметки кодаЗаметки кода, определенные в Markdown, должны содержать определенное свойство frontmatter макетаerrorcode, feature, annotate, frontmatter
GHD017frontmatter-liquid-синтаксисСвойства Frontmatter должны использовать допустимые свойства Liquiderrorжидкость, frontmatter
GHD018синтаксис liquid-Содержимое Markdown должно использовать допустимое содержимое Liquiderrorliquid
GHD019liquid-if-tagsТеги Liquid ifversion следует использовать вместо if тегов, если аргумент является допустимой версией.errorliquid, управление версиями
GHD020liquid-ifversion-tagsТеги Liquid ifversion должны содержать допустимые имена версий в качестве аргументовerrorliquid, управление версиями
GHD0222liquid-ifversion-versionsЖидкость ifversionelsif) не всегда должна быть вернойпредупреждений (не рекомендуется)liquid, управление версиями
GHD035rai-reusable-usageСтатьи RAI и повторно используемые файлы могут ссылаться только на повторное использование содержимого в каталоге data/reusables/rai.errorфункция, rai
GHD036image-no-gifИзображение не должно быть GIF- ссылкой на styleguide: участие/style-guide-and-content-model/style-guide.md#imageserrorimages
GHD038истек срок действия содержимогоСодержимое с истекшим сроком действия должно быть исправлено.errorсрок действия истек
GHD039истекает срок действия в ближайшее времяСрок действия содержимого, срок действия которого истекает в ближайшее время, должен быть упреждаем.предупреждений (не рекомендуется)срок действия истек

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

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

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

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

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

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

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

КомментарийДействие
<!-- markdownlint-disable -->
Отключить все правила
<!-- markdownlint-enable -->
Включение всех правил
<!-- markdownlint-disable-line -->
Отключить все правила для текущей строки
<!-- markdownlint-disable-next-line -->
Отключить все правила для следующей строки
<!-- markdownlint-disable RULE-ONE RULE-TWO -->
Отключение одного или нескольких правил по имени
<!-- markdownlint-enable RULE-ONE RULE-TWO -->
Включение одного или нескольких правил по имени
<!-- markdownlint-disable-line RULE-NAME -->
Отключение одного или нескольких правил по имени текущей строки
<!-- markdownlint-disable-next-line RULE-NAME -->
Отключение одного или нескольких правил по имени для следующей строки