Сведения о содержимом 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
ветвь. Большинство правил в конечном итоге будут повышены до ошибок, так как содержимое больше не имеет предупреждений нарушений.
Идентификатор правила | Имена правил | Description | Серьезность | Теги |
---|---|---|---|---|
MD001 | Увеличение заголовка | Уровни заголовков должны увеличиваться только на один уровень за раз | error | Заголовки |
MD004 | ul-style | Стиль неупорядоченного списка | error | маркер, ul |
MD009 | no-trailing-spaces | Конечные пробелы | error | пробел |
MD011 | no-reversed-links | Синтаксис обратной ссылки | error | ссылки |
MD012 | без нескольких пустых | Несколько последовательных пустых строк | error | пробелы, blank_lines |
MD014 | commands-show-output | Знаки доллара, используемые перед командами без отображения выходных данных | error | кодом |
MD018 | no-missing-space-atx | Нет места после хэш-заголовка стиля atx | error | заголовки, atx, пробелы |
MD019 | no-multiple-space-atx | Несколько пробелов после хэш-заголовка стиля atx | error | заголовки, atx, пробелы |
MD022 | пустые заголовки | Заголовки должны быть окружены пустыми строками | error | заголовки, blank_lines |
MD023 | заголовок-слева | Заголовки должны начинаться в начале строки. | error | заголовки, пробелы |
MD027 | no-multiple-space-blockquote | Несколько пробелов после символа blockquote | error | blockquote, пробелы, отступы |
MD029 | ol-префикс | Префикс упорядоченного элемента списка | error | ol |
MD030 | list-marker-space | Пробелы после маркеров списка | error | ol, ul, пробелы |
MD031 | пустые заборы вокруг | Блоки заборированного кода должны быть окружены пустыми строками | error | код, blank_lines |
MD037 | без пробела в акценте | Пробелы внутри маркеров выделения | error | пробелы, акцент |
MD039 | no-space-in-links | Пробелы внутри текста ссылки | error | пробелы, ссылки |
MD040 | забортный язык кода | Блоки кода, защищенные, должны иметь указанный язык | error | код, язык |
MD042 | no-empty-links | Нет пустых ссылок | error | ссылки |
MD047 | single-trailing-newline | Файлы должны заканчиваться одним символом новой строки | error | blank_lines |
MD049 | стиль акцента | Стиль выделения | error | emphasis |
MD050 | сильный стиль | Сильный стиль | error | emphasis |
search-replace | заполнитель todocs-placeholder | Перехват вхождения заполнителя TODOCS. | error | |
search-replace | docs-domain | Перехват вхождения домена docs.github.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 | |
GH001 | no-default-alt-text | Изображения должны иметь значимый альтернативный текст (замещающий текст) | error | специальные возможности, изображения |
GH002 | no-generic-link-text | Избегайте использования универсального текста ссылки, например Learn more или Click here | error | специальные возможности, ссылки |
GHD030 | длина строки забора кода | Линии ограждения кода не должны превышать максимальную длину | предупреждений (не рекомендуется) | код, специальные возможности |
GHD032 | image-alt-text-end-punctuation | Альтернативный текст для изображений должен заканчиваться знаками препинания | error | специальные возможности, изображения |
GHD004 | image-file-kebab-case | Имена файлов изображений должны использовать kebab-case | error | images |
GHD033 | неверный alt-text-length | Замещающий текст изображений должен составлять от 40 до 150 символов | предупреждений (не рекомендуется) | специальные возможности, изображения |
GHD002 | internal-links-no-lang | Внутренние ссылки не должны иметь жестко закодированный языковой код | error | ссылки, URL-адрес |
GHD003 | внутренняя косая черта | Внутренние ссылки должны начинаться с / | error | ссылки, URL-адрес |
GHD031 | image-alt-text-exclude-words | Альтернативный текст для изображений не должен начинаться с таких слов, как "изображение" или "графический" | error | специальные возможности, изображения |
GHD034 | list-first-word-capitalization | Первое слово элемента списка должно быть заглавно | предупреждений (не рекомендуется) | ul, ol |
GHD001 | препинание ссылок | Заголовки внутренних ссылок не должны содержать знаки препинания | error | ссылки, URL-адрес |
GHD008 | ранние ссылки на access | Файлы, которые не являются ранним доступом, не должны ссылаться на файлы с ранним доступом или ранним доступом | error | функция, ранний доступ |
GHD021 | задания yaml-scheduled-jobs | Фрагменты YAML, включающие запланированные рабочие процессы, не должны выполняться в час и должны быть уникальными | error | функция, действия |
GHD006 | внутренняя версия-links-old-version | Внутренние ссылки не должны иметь жестко закодированную версию с использованием старого синтаксиса управления версиями | error | ссылки, URL-адрес, управление версиями |
GHD005 | hardcoded-data-variable | Строки, содержащие "личный маркер доступа", должны использовать переменную продукта. | error | один источник |
GHD013 | github-owned-action-references | Ссылки на действия, принадлежащие GitHub, не должны быть жестко закодированы | error | функция, действия |
GHD016 | liquid-quoted-условно-arg | Условные теги Liquid не должны кавычки условного аргумента | error | жидкость, формат |
GHD014 | liquid-data-references-defined | Ссылки на ликвидные или отступные данные найдены в содержимом, не имеющих значения или не существующих в каталоге данных. | error | liquid |
GHD015 | формат liquid-data-tag | Теги ссылок на ликвидные или отступные данные должны быть правильно отформатированы и иметь правильное количество аргументов и интервалов | error | жидкость, формат |
GHD010 | frontmatter-hidden-docs | Статьи с свойством hidden frontmatter могут находиться только в определенных продуктах | error | frontmatter, компонент, ранний доступ |
GHD009 | frontmatter-early-access-references | Файлы, которые не являются ранним доступом, не должны иметь интерфейсные элементы, ссылающиеся на ранний доступ | error | frontmatter, компонент, ранний доступ |
GHD011 | frontmatter-video-transcripts | Расшифровка видео должна быть настроена правильно | error | frontmatter, feature, video-transcripts |
GHD012 | frontmatter-schema | Frontmatter должен соответствовать схеме | error | frontmatter, схема |
GHD007 | заметки кода | Заметки кода, определенные в Markdown, должны содержать определенное свойство frontmatter макета | error | code, feature, annotate, frontmatter |
GHD017 | frontmatter-liquid-синтаксис | Свойства Frontmatter должны использовать допустимые свойства Liquid | error | жидкость, frontmatter |
GHD018 | синтаксис liquid- | Содержимое Markdown должно использовать допустимое содержимое Liquid | error | liquid |
GHD019 | liquid-if-tags | Теги Liquid ifversion следует использовать вместо if тегов, если аргумент является допустимой версией. | error | liquid, управление версиями |
GHD020 | liquid-ifversion-tags | Теги Liquid ifversion должны содержать допустимые имена версий в качестве аргументов | error | liquid, управление версиями |
GHD0222 | liquid-ifversion-versions | Жидкость ifversion (и elsif ) не всегда должна быть верной | предупреждений (не рекомендуется) | liquid, управление версиями |
GHD035 | rai-reusable-usage | Статьи RAI и повторно используемые файлы могут ссылаться только на повторное использование содержимого в каталоге data/reusables/rai. | error | функция, rai |
GHD036 | image-no-gif | Изображение не должно быть GIF- ссылкой на styleguide: участие/style-guide-and-content-model/style-guide.md#images | error | images |
GHD038 | истек срок действия содержимого | Содержимое с истекшим сроком действия должно быть исправлено. | error | срок действия истек |
GHD039 | истекает срок действия в ближайшее время | Срок действия содержимого, срок действия которого истекает в ближайшее время, должен быть упреждаем. | предупреждений (не рекомендуется) | срок действия истек |
GHD040 | управление версиями table-liquid | Таблицы должны использовать правильный формат управления версиями liquid | error | В таблицах |
GHD041 | закрепление стороннего действия | Примеры кода, использующие сторонние действия, должны всегда закрепляться на полной длине фиксации SHA | error | функция, действия |
Синтаксис правил подкладки
Некоторые правила подстроки возвращают предупреждения или ошибки на основе 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 -->
Эти комментарии можно использовать для включения или отключения правил.
Комментарий | Действие |
---|---|
<!-- 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 --> | Отключение одного или нескольких правил по имени для следующей строки |