Add support for cURL in application selector (#19645)

Author: Sarah Edwards

content/README.md

@@ -212,8 +212,8 @@ defaultPlatform: linux
 
 ### `defaultTool`
 
-- Purpose: Override the initial tool selection for a page, where tool refers to the application the reader is using to work with GitHub, such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop. If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable.
-- Type: `String`, one of: `webui`, `cli`, `desktop`.
+- Purpose: Override the initial tool selection for a page, where tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs (such as cURL or the GitHub CLI). If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable.
+- Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`.
 - Optional.
 
 ```yaml

contributing/content-markup-reference.md

@@ -102,7 +102,7 @@ You can define a default platform in the frontmatter. For more information, see
 
 ## Tool tags
 
-We occasionally need to write documentation for different tools (GitHub UI, GitHub CLI, GitHub Desktop). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool.
+We occasionally need to write documentation for different tools (GitHub UI, GitHub CLI, GitHub Desktop, cURL). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool.
 
 ### Usage
 
@@ -130,6 +130,14 @@ These instructions are pertinent to GitHub CLI users.
 {% enddesktop %}
 ```
 
+```
+{% curl %}
+
+These instructions are pertinent to cURL users.
+
+{% endcurl %}
+```
+
 Unlike [operating system tags](#operating-system-tags), which will automatically add tabs to select the operating system at the top of the article, you must add `{% include tool-switcher %}` wherever you want to display tabs to select the tool. This allows you to display the tabs at the top of the article or immediately before a relevant section.
 
 You can define a default tool in the frontmatter. For more information, see the [content README](../content/README.md#defaulttool).

includes/tool-switcher.html

@@ -3,6 +3,7 @@
   <div class="UnderlineNav-body">
     <a href="#" class="UnderlineNav-item tool-switcher" data-tool="webui">GitHub.com</a>
     <a href="#" class="UnderlineNav-item tool-switcher" data-tool="cli">CLI</a>
+    <a href="#" class="UnderlineNav-item tool-switcher" data-tool="curl">cURL</a>
     <a href="#" class="UnderlineNav-item tool-switcher" data-tool="desktop">Desktop</a>
   </div>
 </nav>

javascripts/display-tool-specific-content.js

@@ -2,26 +2,29 @@ import Cookies from 'js-cookie'
 
 import { sendEvent } from './events'
 
-const supportedTools = ['cli', 'desktop', 'webui']
-const detectedTools = new Set()
+const supportedTools = ['cli', 'desktop', 'webui', 'curl']
 
 export default function displayToolSpecificContent () {
-  let tool = getDefaultTool()
+  const toolElements = Array.from(document.querySelectorAll('.extended-markdown'))
+    .filter(el => supportedTools.some(tool => el.classList.contains(tool)))
+
+  const detectedTools = toolElements
+    .flatMap(el => Array.from(el.classList).filter(className => supportedTools.includes(className)))
 
-  if (!tool) tool = 'webui'
+  const tool = getDefaultTool(detectedTools)
 
-  const toolsInContent = findToolSpecificContent(tool)
+  showToolSpecificContent(tool, toolElements)
 
-  hideSwitcherLinks(toolsInContent)
+  hideSwitcherLinks(detectedTools)
 
-  showContentForTool(tool)
+  highlightTabForTool(tool)
 
   // configure links for switching tool content
   switcherLinks().forEach(link => {
     link.addEventListener('click', (event) => {
       event.preventDefault()
-      showContentForTool(event.target.dataset.tool)
-      findToolSpecificContent(event.target.dataset.tool)
+      highlightTabForTool(event.target.dataset.tool)
+      showToolSpecificContent(event.target.dataset.tool, toolElements)
 
       // Save this preference as a cookie.
       Cookies.set('toolPreferred', event.target.dataset.tool, { sameSite: 'strict', secure: true })
@@ -36,7 +39,7 @@ export default function displayToolSpecificContent () {
   })
 }
 
-function showContentForTool (tool) {
+function highlightTabForTool (tool) {
   // (de)activate switcher link appearances
   switcherLinks().forEach(link => {
     (link.dataset.tool === tool)
@@ -45,52 +48,45 @@ function showContentForTool (tool) {
   })
 }
 
-function findToolSpecificContent (tool) {
-  // find all tool-specific *block* elements and hide or show as appropriate
-  // example: {{ #cli }} block content {{/cli}}
-  Array.from(document.querySelectorAll('.extended-markdown'))
-    .filter(el => supportedTools.some(tool => el.classList.contains(tool)))
-    .forEach(el => {
-      detectTools(el)
-      el.style.display = el.classList.contains(tool)
-        ? ''
-        : 'none'
-    })
-
-  // find all tool-specific *inline* elements and hide or show as appropriate
-  // example: <span class="tool-cli">inline content</span>
-  Array.from(document.querySelectorAll('.tool-cli, .tool-desktop, .tool-webui'))
+function showToolSpecificContent (tool, toolElements) {
+  // show the content only for the highlighted tool
+  toolElements
+    .filter(el => supportedTools.some(tool => (el.classList.contains(tool))))
     .forEach(el => {
-      detectTools(el)
-      el.style.display = el.classList.contains('tool-' + tool)
+      el.style.display = (el.classList.contains(tool))
         ? ''
         : 'none'
     })
-
-  return Array.from(detectedTools)
 }
 
 // hide links for any tool-specific sections that are not present
-function hideSwitcherLinks (toolsInContent) {
+function hideSwitcherLinks (detectedTools) {
   Array.from(document.querySelectorAll('a.tool-switcher'))
     .forEach(link => {
-      if (toolsInContent.includes(link.dataset.tool)) return
+      if (detectedTools.includes(link.dataset.tool)) return
       link.style.display = 'none'
     })
 }
 
-function detectTools (el) {
-  el.classList.forEach(elClass => {
-    const value = elClass.replace(/tool-/, '')
-    if (supportedTools.includes(value)) detectedTools.add(value)
-  })
-}
-
-function getDefaultTool () {
+function getDefaultTool (detectedTools) {
+  // If the user selected a tool preference and the tool is present on this page
   const cookieValue = Cookies.get('toolPreferred')
-  if (cookieValue) return cookieValue
-  const el = document.querySelector('[data-default-tool]')
-  if (el) return el.dataset.defaultTool
+  if (cookieValue && detectedTools.includes(cookieValue)) return cookieValue
+
+  // If there is a default tool and the tool is present on this page
+  const defaultToolEl = document.querySelector('[data-default-tool]')
+  if (defaultToolEl && detectedTools.includes(defaultToolEl.dataset.defaultTool)) {
+    return defaultToolEl.dataset.defaultTool
+  }
+
+  // Default to webui if present (this is generally the case where we show UI/CLI/Desktop info)
+  if (detectedTools.includes('webui')) return 'webui'
+
+  // Default to cli if present (this is generally the case where we show curl/CLI info)
+  if (detectedTools.includes('cli')) return 'cli'
+
+  // Otherwise, just choose the first detected tool
+  return detectedTools[0]
 }
 
 function switcherLinks () {

lib/frontmatter.js

@@ -137,7 +137,7 @@ const schema = {
     // Tool-specific content preference
     defaultTool: {
       type: 'string',
-      enum: ['webui', 'cli', 'desktop']
+      enum: ['webui', 'cli', 'desktop', 'curl']
     },
     // Documentation contributed by a third party, such as a GitHub Partner
     contributor: {

lib/liquid-tags/extended-markdown.js

@@ -5,6 +5,7 @@ const tags = {
   cli: '',
   desktop: '',
   webui: '',
+  curl: '',
   all: '',
   tip: 'border rounded-1 mb-4 p-3 color-border-info color-bg-info f5',
   note: 'border rounded-1 mb-4 p-3 color-border-info color-bg-info f5',

lib/schema-event.js

@@ -118,7 +118,7 @@ const context = {
     }, */
     application_preference: {
       type: 'string',
-      enum: ['webui', 'cli', 'desktop'],
+      enum: ['webui', 'cli', 'desktop', 'curl'],
       description: 'The application selected by the user.'
     }
     /* color_mode_preference: {
@@ -413,7 +413,7 @@ const preferenceSchema = {
     },
     preference_value: {
       type: 'string',
-      enum: ['webui', 'cli', 'desktop'],
+      enum: ['webui', 'cli', 'desktop', 'curl'],
       description: 'The application selected by the user.'
     }
   }