Acerca de los conmutadores de herramientas
En algunos artículos, escribimos contenido adaptado a diferentes herramientas (la interfaz de usuario de GitHub, la GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, GraphQL API, etc.) El conmutador de herramientas permite a los usuarios seleccionar una herramienta para ver solo el contenido que es pertinente para esa herramienta, ya que las herramientas pueden tener información conceptual o de procedimientos diferente.
Los usuarios pueden utilizar el conmutador de herramientas de dos maneras al leer los documentos.
-
Explorando En el caso de las tareas que se pueden completar con distintas herramientas, el conmutador de herramientas indica a los usuarios que hay varias maneras de realizar una tarea. Por ejemplo, mediante la GitHub CLI o GitHub Desktop, en lugar de la interfaz de usuario de GitHub.
-
Yendo al grano Cuando alguien sabe cómo quiere realizar una tarea y no necesita ver opciones adicionales, el conmutador de herramientas quita el contenido menos pertinente para que pueda encontrar exactamente lo que necesita.
Uso de etiquetas de herramientas
Puedes agregar conmutadores de herramientas a un artículo mediante etiquetas de herramientas en Markdown. Las etiquetas de herramientas son etiquetas de Liquid que encapsulan el contenido que deseas mostrar en una pestaña específica del conmutador de herramientas.
Por ejemplo, el siguiente bloque de código muestra contenido para tres herramientas diferentes.
{% 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 %}
De forma predeterminada, se seleccionará la primera etiqueta de herramienta de Markdown para un artículo. Puedes definir una herramienta predeterminada diferente para un artículo especificando una propiedad defaultTool: en el texto preliminar del artículo. Para obtener más información, consulta el contenido README.
También puedes vincular a un artículo con una herramienta específica seleccionada mediante la adición de ?tool=TOOLNAME al final del vínculo. Para más información, consulta Guía de estilo.
Incluye solo un máximo de ocho herramientas diferentes en un artículo. La inclusión de más herramientas hace que las pestañas del conmutador de herramientas se desborden con la tabla de contenido de un artículo, lo que impide que los usuarios utilicen el conmutador de herramientas o la tabla de contenido. Es improbable que alguna vez tengas que incluir ocho herramientas independientes en un artículo. En general, planea usar la menor cantidad posible de herramientas independientes en un artículo.
Cuándo usar etiquetas de herramientas
Solo usamos etiquetas de herramientas si un artículo debe tener información específica de la herramienta para ayudar a los usuarios a realizar sus tareas.
No uses el conmutador de herramientas solo para mostrar ejemplos en distintos idiomas. Usa el conmutador de herramientas solo si las tareas o conceptos descritos en un artículo cambian en función de la herramienta usada por alguien.
Adición de nuevas herramientas
GitHub Docs documenta y mantiene etiquetas de herramientas para productos GitHub, herramientas desarrolladas por GitHub y extensiones de terceros seleccionadas desarrolladas en colaboración con GitHub.
Las nuevas herramientas solo se agregan cuando son la única manera de documentar con precisión algo para una necesidad específica del usuario. Si un escritor determina que agregar una nueva herramienta es la única manera de documentar algo con precisión, debe proponer la nueva herramienta en un plan de diseño de contenido. Cualquiera que revise el plan de diseño de contenido debe tener en cuenta cualquier alternativa de abordar las necesidades de documentación sin agregar una nueva herramienta. Si una nueva herramienta es la única manera de crear documentación precisa, se debe agregar la nueva herramienta. Si hay una solución de contenido alternativa que no agrega una nueva herramienta, se debe usar esa opción.
Para agregar una nueva herramienta, agrega una entrada al objeto allTools en el archivo lib/all-tools.js como un par clave-valor. La clave es la etiqueta que se usa para hacer referencia a la herramienta en el artículo y el valor es cómo se identificará la herramienta en el selector de herramientas en la parte superior del artículo. Por ejemplo, vscode: 'Visual Studio Code'.
Agrega nuevas herramientas en orden alfabético.