Сведения о переключателях инструментов
В некоторых статьях мы записываем содержимое, адаптированное к различным средствам (пользовательский интерфейс GitHub, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, API GraphQL и т. д.) Переключатель инструментов позволяет пользователям выбирать инструмент, чтобы увидеть только содержимое, соответствующее этому инструменту, так как средства могут иметь различные концептуальные или процедурные сведения.
Пользователи могут использовать переключатель инструментов двумя способами при чтении документации.
-
Изучение . Для задач, которые можно выполнить с различными инструментами, средство переключает сигналы людям о том, что можно выполнить задачу несколькими способами. Например, использование GitHub CLI или GitHub Desktopвместо пользовательского интерфейса GitHub.
-
Переход к точке . Когда кто-то знает, как они хотят выполнить задачу и не нужно видеть дополнительные параметры, переключатель инструментов удаляет менее релевантное содержимое, чтобы они могли найти именно то, что им нужно.
Использование тегов инструментов
Вы можете добавить переключатели инструментов в статью с помощью тегов инструментов в Markdown. Теги инструментов — это теги Liquid, которые содержат содержимое, которое нужно отобразить на определенной вкладке переключателя инструментов.
Например, в следующем блоке кода отображается содержимое для трех различных инструментов.
{% vscode %}
This content is specific to Visual Studio Code.
{% endvscode %}
{% visualstudio %}
This content is specific to Visual Studio.
{% endvisualstudio %}
{% jetbrains %}
This content is specific to JetBrains IDEs.
{% endjetbrains %}
По умолчанию первый тег средства, используемый в Markdown, будет выбран для статьи. Вы можете определить другое средство по умолчанию для статьи, указав defaultTool: свойство в интерфейсном элементе статьи. Дополнительные сведения см. в содержимом README.
Вы также можете связаться со статьей с определенным средством, выбранным путем добавления ?tool=TOOLNAME в конец ссылки. Дополнительные сведения см. в разделе Руководство по стилю.
В статью входит только не более восьми различных инструментов. Включение дополнительных инструментов приводит к переполнению вкладок переключателя инструментов с оглавлением статьи, что запрещает пользователям использовать переключатель инструментов или оглавление. Вряд ли вам потребуется включить восемь отдельных инструментов в статью. Как правило, планируйте использовать как можно меньше отдельных инструментов в статье.
Когда следует использовать теги инструментов
Мы используем только теги инструментов, если в статье должны быть сведения, относящиеся к инструменту, чтобы помочь людям выполнять свои задачи.
Не используйте переключатель инструментов только для отображения примеров на разных языках. Используйте переключатель инструментов только в том случае, если задачи или понятия, описанные в статье, изменяются на основе того, какой инструмент использует кто-то.
Добавление новых инструментов
GitHub Docs документы и поддерживает теги инструментов для продуктов GitHub, GitHub, разработанных средствами, и выбирают сторонние расширения, разработанные в сотрудничестве с GitHub .
Новые инструменты добавляются только в том случае, если они являются единственным способом точно документировать что-то для конкретного пользователя. Если средство записи определяет, что добавление нового инструмента является единственным способом точно документировать что-то, им нужно предложить новое средство в плане разработки контента. Независимо от того, кто проверяет план разработки контента, следует рассмотреть любые альтернативные способы решения потребностей документации без добавления нового инструмента. Если новое средство является единственным способом создания точной документации, необходимо добавить новое средство. Если существует альтернативное решение для содержимого, которое не добавляет новое средство, этот параметр следует использовать.
Чтобы добавить новое средство, добавьте запись в allTools объект в файле в lib/all-tools.js виде пары "ключ-значение". Ключ — это тег, используемый для ссылки на инструмент в статье, и значение заключается в том, как средство будет идентифицировано в средстве выбора в верхней части статьи. Например, vscode: 'Visual Studio Code'.
Добавьте новые инструменты в алфавитном порядке.