Сведения о переключателях инструментов
В некоторых статьях мы записываем содержимое, адаптированное к различным средствам (пользовательский интерфейс GitHub, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, API GraphQL и т. д.) Переключатель инструментов позволяет пользователям выбирать инструмент, чтобы увидеть только содержимое, соответствующее этому инструменту, так как средства могут иметь различные концептуальные или процедурные сведения. Люди можно использовать переключатель инструментов двумя способами при чтении документации.
Изучение задач, которые можно выполнить с различными инструментами, средство переключения сигнализирует людям о том, что можно выполнить задачу несколькими способами. Например, использование GitHub CLI или GitHub Desktopвместо пользовательского интерфейса GitHub.
Переход к точке , когда кто-то знает, как они хотят выполнить задачу и не нужно видеть дополнительные параметры, переключатель инструментов удаляет менее релевантное содержимое, чтобы они могли найти именно то, что им нужно.
Использование тегов инструментов
Теги инструментов используются для разделения сведений для каждого средства. В редких случаях мы добавим новые инструменты.
Теги инструментов — это пара значений ключа. Ключ — это тег, используемый для ссылки на инструмент в статье, и значение заключается в том, как средство будет идентифицировано в средстве выбора в верхней части статьи. Существующие средства находятся в lib/all-tools.js репозитории GitHub Docs .
Когда следует использовать теги инструментов
Мы используем только теги инструментов, если в статье должны быть сведения, относящиеся к инструменту, чтобы помочь людям выполнять свои задачи. Если концептуальные сведения или процедурные шаги для задачи значительно отличаются в зависимости от того, какой инструмент использует пользователь, и мы хотим, чтобы люди могли выполнять задачу с различными инструментами, мы используем теги инструментов для представления соответствующей информации в статье.
Не используйте переключатель инструментов только для отображения примеров на разных языках. Используйте переключатель инструментов только в том случае, если задачи или понятия, описанные в статье, изменяются на основе того, какой инструмент использует кто-то.
Использование тегов инструментов
Теги инструментов — это теги Liquid, которые содержат содержимое, относящееся к инструменту.
Поместите инструменты в алфавитном порядке. По умолчанию для статьи будет выбран первый тег средства. Вы можете определить другое средство по умолчанию для статьи, указав defaultTool: свойство в интерфейсном элементе статьи. Дополнительные сведения см. в содержимом README.
Вы также можете связаться со статьей с определенным средством, выбранным путем добавления ?tool=TOOLNAME в конец ссылки. Дополнительные сведения см. в разделе Руководство по стилю.
В статью входит только не более восьми различных инструментов. Включение дополнительных инструментов приводит к переполнению вкладок переключателя инструментов с оглавлением статьи, что запрещает пользователям использовать переключатель инструментов или оглавление. Вряд ли вам потребуется включить восемь отдельных инструментов в статью. Как правило, планируйте использовать как можно меньше отдельных инструментов в статье.
Добавление новых инструментов
GitHub Docs документы и поддерживает теги инструментов для продуктов GitHub, GitHub, разработанных средствами, и выбирают сторонние расширения, разработанные в сотрудничестве с GitHub .
Новые инструменты добавляются только в том случае, если они являются единственным способом точно документировать что-то для конкретного пользователя. Если средство записи определяет, что добавление нового инструмента является единственным способом точно документировать что-то, им нужно предложить новое средство в плане разработки контента. Кто в зависимости от плана разработки содержимого следует рассмотреть любые альтернативные способы решения потребностей документации без добавления нового инструмента. Если новое средство является единственным способом создания точной документации, необходимо добавить новое средство. Если существует альтернативное решение для содержимого, которое не добавляет новое средство, этот параметр следует использовать.
Чтобы добавить новое средство, добавьте запись в allTools объект в файле в lib/all-tools.js виде пары "ключ-значение". Добавьте новые инструменты в алфавитном порядке.