Skip to main content

在文章中创建工具切换器

可以使用工具切换器来演示如何使用特定工具完成任务。

“参与 GitHub Docs”部分中的文章指的是文档本身,是 GitHub 员工和开放源代码参与者的资源。

关于工具切换器

在某些文章中,我们针对不同工具(GitHub UI、GitHub CLI、GitHub Desktop、cURL、Codespaces、VS Code、GraphQL API 等)编写定制的内容。通过工具切换器,人员可以选择一种工具,仅查看与该工具相关的内容,因为各个工具可能具有不同的概念或过程信息。 人员在阅读文档时可以通过两种方式使用工具切换器。

探索:对于可以使用不同工具完成的任务,工具切换器会向人员发出信号,告知他们可通过多种方式完成任务。 例如,使用 GitHub CLI 或 GitHub Desktop,而不是 GitHub UI。

把握要点:当人员知道他们想要如何执行任务并且不需要查看其他选项时,工具切换器会删除不太相关的内容,这样他们就可以准确地找到所需的内容。

使用工具标记

我们使用工具标记来划分每个工具的信息。 在极少数情况下,我们将添加新工具。

工具标记是键值对。 键是用于在文章中引用工具的标记,值是在文章顶部的工具选取器上标识该工具的方式。 现有工具位于 GitHub Docs 存储库中的 lib/all-tools.js 中。

何时使用工具标记

仅当文章必须具有特定于工具的信息来帮助人员完成任务时,我们才使用工具标记。 如果任务的概念信息或过程步骤因人员使用的工具而明显不同,并且我们希望人员能够使用不同的工具完成任务,我们将使用工具标记在文章中呈现相关信息。

请勿仅仅为了显示不同语言的示例而使用工具切换器。 仅当文章中所述的任务或概念根据人员使用的工具发生更改时,才使用工具切换器。

如何使用工具标记

工具标记是包装特定于工具的内容的 Liquid 标记。

按字母顺序放置工具。 默认情况下,将为文章选择第一个工具标记。 可以通过在文章的前辅文中指定 defaultTool: 属性,为文章定义不同的默认工具。 有关详细信息,请参阅内容自述文件

还可以通过将 ?tool=TOOLNAME 添加到链接末尾,链接到选择了特定工具的文章。 有关详细信息,请参阅“风格指南”。

一篇文章中最多只包含 8 种不同的工具。 包含更多工具会导致工具切换器选项卡溢出文章的目录,从而阻止人员使用工具切换器或目录。 不太可能需要在文章中包含 8 种独立工具。 通常,计划在文章中使用尽可能少的独立工具。

添加新工具

GitHub Docs 记录并维护 GitHub 产品、GitHub 开发的工具、选定第三方扩展的工具标记。

只有当新工具是准确记录特定用户需要的内容的唯一方式时,才会添加新工具。 如果编写者确定添加新工具是准确记录某些内容的唯一方法,则必须在内容设计阶段提出使用新工具。 审阅内容设计计划的人员应考虑是否有其他方法,可以在不添加新工具的情况下满足记录需求。 如果新工具是创建准确文档的唯一方法,则应添加新工具。 如果有不添加新工具的替代内容解决方案,则应使用该选项。

若要添加新工具,请将一个条目作为键值对添加到 lib/all-tools.js 文件中的 allTools 对象。 按字母顺序添加新工具。