Merge pull request #1917 from Simran-B/default-platform

Add support for page.defaultPlatform frontmatter

Author: chiedo

content/README.md

@@ -20,6 +20,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [`showMiniToc`](#showminitoc)
   - [`miniTocMaxHeadingLevel`](#minitocmaxheadinglevel)
   - [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
+  - [`defaultPlatform`](#defaultplatform)
   - [Escaping single quotes](#escaping-single-quotes)
 - [Autogenerated mini TOCs](#autogenerated-mini-tocs)
 - [Versioning](#versioning)
@@ -172,6 +173,18 @@ featuredLinks:
 - Type: `Array`, items are objects `{ href: string, title: string, date: 'YYYY-MM-DD' }`
 - Optional.
 
+### `defaultPlatform`
+
+- Purpose: Override the initial platform selection for a page. If this frontmatter is omitted, then the platform-specific content matching the reader's operating system is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable. For example, most GitHub Actions runners use Linux and their operating system is independent of the reader's operating system.
+- Type: `String`, one of: `mac`, `windows`, `linux`.
+- Optional.
+
+Example:
+
+```yaml
+defaultPlatform: linux
+```
+
 ### Escaping single quotes
 
 If you see two single quotes in a row (`''`) in YML frontmatter where you might expect to see one (`'`), this is the YML-preferred way to escape a single quote. From [the YAML spec](https://yaml.org/spec/history/2001-12-10.html):

content/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service.md

@@ -6,6 +6,7 @@ redirect_from:
 versions:
   free-pro-team: '*'
   enterprise-server: '>=2.22'
+defaultPlatform: linux
 ---
 
 {% data reusables.actions.enterprise-beta %}

content/actions/hosting-your-own-runners/monitoring-and-troubleshooting-self-hosted-runners.md

@@ -8,6 +8,7 @@ redirect_from:
 versions:
   free-pro-team: '*'
   enterprise-server: '>=2.22'
+defaultPlatform: linux
 ---
 
 {% data reusables.actions.enterprise-beta %}

contributing/content-markup-reference.md

@@ -38,10 +38,10 @@ For information on when to use callout tags, see the [style guide](content-style
 
 To render syntax highlighting in command line instructions, we use triple backticks followed by the term `shell`.
 
-### Usage  
-  
-    ```shell  
-    git init <em>YOUR_REPO</em>  
+### Usage
+
+    ```shell
+    git init <em>YOUR_REPO</em>
     ```
 
 This syntax highlighting renders light text on a dark background, and should be reserved for command line instructions.
@@ -62,9 +62,11 @@ Octicons are icons used across GitHub’s interface. We reference Octicons when
 
 ### Usage
 
-`{% octicon "<name of octicon>" %}`  
-`{% octicon "plus" %}`
-`{% octicon "plus" aria-label="The plus icon" %}`
+```
+{% octicon "<name of octicon>" %}
+{% octicon "plus" %}
+{% octicon "plus" aria-label="The plus icon" %}
+```
 
 ## Operating system tags
 
@@ -79,27 +81,24 @@ These instructions are pertinent to Mac users.
 
 {% endmac %}
 ```
+
 ```
 {% windows %}
 
 These instructions are pertinent to Windows users.
 
 {% endwindows %}
 ```
+
 ```
 {% linux %}
 
  These instructions are pertinent to Linux users.
 
 {% endlinux %}
 ```
-```
-{% all %}
 
-Though rare, these instructions are pertinent to any other operating system.
-
-{% endall %}
-```
+You can define a default platform in the frontmatter, see the [content README](../content/README.md#defaultplatform).
 
 ## Reusable and variable strings of text
 

includes/article.html

@@ -29,12 +29,12 @@ <h1 class="border-bottom-0">{{ page.title }}</h1>
       {% endif %}
 
       {% if page.includesPlatformSpecificContent %}
-        <nav class="UnderlineNav my-3">
+        <nav class="UnderlineNav my-3"
+        {%- if page.defaultPlatform %} data-default-platform="{{ page.defaultPlatform }}"{% endif %}>
           <div class="UnderlineNav-body">
             <a href="#" class="UnderlineNav-item platform-switcher" data-platform="mac">Mac</a>
             <a href="#" class="UnderlineNav-item platform-switcher" data-platform="windows">Windows</a>
             <a href="#" class="UnderlineNav-item platform-switcher" data-platform="linux">Linux</a>
-            <a href="#" class="UnderlineNav-item platform-switcher" data-platform="all">All</a>
           </div>
         </nav>
       {% endif %}

javascripts/display-platform-specific-content.js

@@ -5,7 +5,7 @@ const detectedPlatforms = new Set()
 // Emphasize content for the visitor's OS (inferred from user agent string)
 
 export default function displayPlatformSpecificContent () {
-  let platform = getPlatformFromUserAgent()
+  let platform = getDefaultPlatform() || getPlatformFromUserAgent()
 
   // adjust platform names to fit existing mac/windows/linux scheme
   if (!platform) platform = 'mac' // default to 'mac' on mobile
@@ -78,6 +78,11 @@ function detectPlatforms (el) {
   })
 }
 
+function getDefaultPlatform () {
+  const el = document.querySelector('[data-default-platform]')
+  if (el) return el.dataset.defaultPlatform
+}
+
 function switcherLinks () {
   return Array.from(document.querySelectorAll('a.platform-switcher'))
 }

lib/frontmatter.js

@@ -100,6 +100,11 @@ const schema = {
     },
     interactive: {
       type: 'boolean'
+    },
+    // Platform-specific content preference
+    defaultPlatform: {
+      type: 'string',
+      enum: ['mac', 'windows', 'linux']
     }
   }
 }

lib/page.js

@@ -197,7 +197,7 @@ class Page {
     const $ = cheerio.load(html)
 
     // set a flag so layout knows whether to render a mac/windows/linux switcher element
-    this.includesPlatformSpecificContent = $('[class^="platform-"], .mac, .windows, .linux, .all').length > 0
+    this.includesPlatformSpecificContent = $('[class^="platform-"], .mac, .windows, .linux').length > 0
 
     // rewrite asset paths to s3 if it's a dotcom article on any GHE version
     // or if it's an enterprise article on any GHE version EXCEPT latest version

package.json

@@ -160,7 +160,7 @@
     "prebrowser-test": "npm run build",
     "browser-test": "start-server-and-test browser-test-server 4001 browser-test-tests",
     "browser-test-server": "cross-env NODE_ENV=production ENABLED_LANGUAGES='en,ja' PORT=4001 node server.js",
-    "browser-test-tests": "BROWSER=1 jest tests/browser/browser.js",
+    "browser-test-tests": "cross-env BROWSER=1 jest tests/browser/browser.js",
     "sync-search": "start-server-and-test sync-search-server 4002 sync-search-indices",
     "sync-search-dry-run": "DRY_RUN=1 npm run sync-search",
     "sync-search-server": "cross-env NODE_ENV=production PORT=4002 node server.js",

tests/browser/browser.js

@@ -172,3 +172,80 @@ async function getLocationObject (page) {
   })
   return JSON.parse(location)
 }
+
+describe('platform specific content', () => {
+  // from tests/javascripts/user-agent.js
+  const userAgents = [
+    { name: 'Mac', id: 'mac', ua: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9' },
+    { name: 'Windows', id: 'windows', ua: 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36' },
+    { name: 'Linux', id: 'linux', ua: 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:15.0) Gecko/20100101 Firefox/15.0.1' }
+  ]
+  const linuxUserAgent = userAgents[2]
+  const pageWithSwitcher = 'http://localhost:4001/en/actions/hosting-your-own-runners/monitoring-and-troubleshooting-self-hosted-runners'
+  const pageWithoutSwitcher = 'http://localhost:4001/en/github/using-git'
+  const pageWithDefaultPlatform = 'http://localhost:4001/en/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service'
+
+  it('should have a platform switcher', async () => {
+    await page.goto(pageWithSwitcher)
+    const nav = await page.$$('nav.UnderlineNav')
+    const switches = await page.$$('a.platform-switcher')
+    const selectedSwitch = await page.$$('a.platform-switcher.selected')
+    expect(nav).toHaveLength(1)
+    expect(switches.length).toBeGreaterThan(1)
+    expect(selectedSwitch).toHaveLength(1)
+  })
+
+  it('should NOT have a platform switcher', async () => {
+    await page.goto(pageWithoutSwitcher)
+    const nav = await page.$$('nav.UnderlineNav')
+    const switches = await page.$$('a.platform-switcher')
+    const selectedSwitch = await page.$$('a.platform-switcher.selected')
+    expect(nav).toHaveLength(0)
+    expect(switches).toHaveLength(0)
+    expect(selectedSwitch).toHaveLength(0)
+  })
+
+  it('should detect platform from user agent', async () => {
+    for (const agent of userAgents) {
+      await page.setUserAgent(agent.ua)
+      await page.goto(pageWithSwitcher)
+      const selectedPlatformElement = await page.waitForSelector('a.platform-switcher.selected')
+      const selectedPlatform = await page.evaluate(el => el.textContent, selectedPlatformElement)
+      expect(selectedPlatform).toBe(agent.name)
+    }
+  })
+
+  it('should prefer defaultPlatform from frontmatter', async () => {
+    for (const agent of userAgents) {
+      await page.setUserAgent(agent.ua)
+      await page.goto(pageWithDefaultPlatform)
+      const defaultPlatform = await page.$eval('[data-default-platform]', el => el.dataset.defaultPlatform)
+      const selectedPlatformElement = await page.waitForSelector('a.platform-switcher.selected')
+      const selectedPlatform = await page.evaluate(el => el.textContent, selectedPlatformElement)
+      expect(defaultPlatform).toBe(linuxUserAgent.id)
+      expect(selectedPlatform).toBe(linuxUserAgent.name)
+    }
+  })
+
+  it('should show the content for the selected platform only', async () => {
+    await page.goto(pageWithSwitcher)
+
+    const platforms = ['mac', 'windows', 'linux']
+    for (const platform of platforms) {
+      await page.click(`.platform-switcher[data-platform="${platform}"]`)
+
+      // content for selected platform is expected to become visible
+      await page.waitForSelector(`.extended-markdown.${platform}`, { visible: true, timeout: 3000 })
+
+      // only a single tab should be selected
+      const selectedSwitch = await page.$$('a.platform-switcher.selected')
+      expect(selectedSwitch).toHaveLength(1)
+
+      // content for NOT selected platforms is expected to become hidden
+      const otherPlatforms = platforms.filter(e => e !== platform)
+      for (const other of otherPlatforms) {
+        await page.waitForSelector(`.extended-markdown.${other}`, { hidden: true, timeout: 3000 })
+      }
+    }
+  })
+})