Merge pull request #16783 from github/early-access-tweaks

Early Access followup work

Author: sarahs

data/ui.yml

@@ -17,7 +17,7 @@ header:
       still in translation. For the most up-to-date and accurate information,
       please visit our
       <a id="to-english-doc" href="/en">English documentation</a>.
-    early_access: 👋 This page contains content about an early access feature. Please do not share this URL publicly.
+    early_access: 📣 Please <b>do not share</b> this URL publicly. This page contains content about an early access feature.
 search:
   need_help: Need help?
   placeholder: Search topics, products...

includes/breadcrumbs.html

@@ -1,7 +1,7 @@
 <nav class="breadcrumbs f5" aria-label="Breadcrumb">
   {% for breadcrumb in breadcrumbs %}
-  {% if page.hidden %}
-  <span class="d-inline-block">{{breadcrumb[1].title}}</span>
+  {% if breadcrumb[1].href == '' %}
+  <span>{{breadcrumb[1].title}}</span>
   {% else %}
   <a title="{{ breadcrumb[0]}}: {{breadcrumb[1].title}}" href="/{{currentLanguage}}{{breadcrumb[1].href}}" class="d-inline-block {% if breadcrumb[1].href == currentPathWithoutLanguage %}text-gray-light{% endif %}">
     {{breadcrumb[1].title}}</a>

includes/header-notification.html

@@ -49,7 +49,7 @@
 {% endif %}
 
 {% if early_access_notification_type %}
-  <div class="header-notifications text-center f5 bg-blue-1 text-gray-dark py-4 px-6 early_access">
+  <div class="header-notifications text-center f5 bg-red-1 text-gray-dark py-4 px-6 early_access">
     {{ early_access_notification }}
   </div>
 {% endif %}

middleware/breadcrumbs.js

@@ -2,9 +2,12 @@ const path = require('path')
 const { getPathWithoutLanguage } = require('../lib/path-utils')
 
 module.exports = async (req, res, next) => {
+  if (!req.context.page) return next()
+  if (req.context.page.hidden) return next()
+
   req.context.breadcrumbs = {}
 
-  if (!req.context.page) return next()
+  // Return an empty object on the landing page
   if (req.context.page.relativePath === 'index.md') return next()
 
   const rawPath = getPathWithoutLanguage(req.path)

middleware/early-access-breadcrumbs.js

@@ -0,0 +1,69 @@
+const path = require('path')
+const { getPathWithoutLanguage } = require('../lib/path-utils')
+
+// Early Access content doesn't conform to the same structure as other products, so we
+// can't derive breadcrumbs from the siteTree in the same way. Hence, this separate middleware.
+module.exports = async (req, res, next) => {
+  if (!req.context.page) return next()
+  if (!req.context.page.hidden) return next()
+
+  req.context.breadcrumbs = {}
+
+  const earlyAccessProduct = req.context.siteTree[req.language][req.context.currentVersion].products[req.context.currentProduct]
+
+  req.context.breadcrumbs.earlyAccessProduct = {
+    href: '', // no link for the EA product breadcrumb
+    title: earlyAccessProduct.title
+  }
+
+  const rawPath = getPathWithoutLanguage(req.path)
+  const pathParts = rawPath.split('/')
+
+  // drop first '/'
+  pathParts.shift()
+
+  // drop the version and early-accesss segments so pathParts now starts with /product
+  pathParts.shift()
+  pathParts.shift()
+
+  // Early Access products do not require an index.md, so look for a matching public product
+  const product = req.context.siteTree[req.language][req.context.currentVersion].products[pathParts[0]]
+
+  if (!product) return next()
+
+  req.context.breadcrumbs.product = {
+    href: '', // no link for the EA product breadcrumbs
+    title: product.title
+  }
+
+  if (!pathParts[1]) return next()
+
+  // get Early Access category path
+  // e.g., `enforcing-best-practices-with-github-policies` in /free-pro-team@latest/early-access/github/enforcing-best-practices-with-github-policies
+  const categoryPath = path.posix.join('/', req.context.currentVersion, 'early-access', pathParts[0], pathParts[1])
+  const category = req.context.pages[path.posix.join('/en', categoryPath)]
+
+  if (!category) return next()
+
+  req.context.breadcrumbs.category = {
+    href: categoryPath, // do include a link for EA category breadcrumbs
+    title: category.shortTitle || category.title
+  }
+
+  if (!pathParts[2]) return next()
+
+  // for Early Access purposes, we don't need to differentiate between map topics and articles breadcrumbs
+  const mapTopicOrArticlePath = path.posix.join(categoryPath, pathParts[2])
+  const mapTopicOrArticle = req.context.pages[path.posix.join('/en', mapTopicOrArticlePath)]
+
+  if (!mapTopicOrArticle) return next()
+
+  const mapTopicOrArticleTitle = await mapTopicOrArticle.renderProp('shortTitle', req.context, { textOnly: true, encodeEntities: true })
+
+  req.context.breadcrumbs.article = {
+    href: mapTopicOrArticlePath, // do include a link for EA map topic/article breadcrumbs
+    title: mapTopicOrArticleTitle
+  }
+
+  return next()
+}

middleware/index.js

@@ -73,6 +73,7 @@ module.exports = function (app) {
   app.use(require('./contextualizers/rest'))
   app.use(require('./contextualizers/webhooks'))
   app.use(require('./breadcrumbs'))
+  app.use(require('./early-access-breadcrumbs'))
   app.use(require('./dev-toc'))
   app.use(require('./featured-links'))
 

stylesheets/article.scss

@@ -87,7 +87,7 @@
 /* Breadcrumbs
 ------------------------------------------------------------------------------*/
 
-.breadcrumbs a:not(:last-child)::after{
+.breadcrumbs a:not(:last-child)::after, .breadcrumbs span:not(:last-child)::after {
   content: '/';
   color: $gray-400;
   padding-right: $spacer-1;

tests/rendering/breadcrumbs.js

@@ -1,6 +1,8 @@
 const { getDOM, getJSON } = require('../helpers/supertest')
 const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version')
 
+const describeInternalOnly = process.env.GITHUB_REPOSITORY === 'github/docs-internal' ? describe : describe.skip
+
 describe('breadcrumbs', () => {
   jest.setTimeout(300 * 1000)
 
@@ -60,6 +62,27 @@ describe('breadcrumbs', () => {
     })
   })
 
+  describeInternalOnly('early access rendering', () => {
+    test('top-level product pages have breadcrumbs', async () => {
+      const $ = await getDOM('/early-access/github/articles/using-gist-playground')
+      expect($('.breadcrumbs')).toHaveLength(1)
+    })
+
+    test('early access article pages have breadcrumbs with product, category, and article', async () => {
+      const $ = await getDOM('/early-access/github/enforcing-best-practices-with-github-policies/about-github-policies')
+      const $breadcrumbSpans = $('.breadcrumbs span')
+      const $breadcrumbLinks = $('.breadcrumbs a')
+
+      expect($breadcrumbSpans).toHaveLength(2)
+      expect($breadcrumbLinks).toHaveLength(2)
+      expect($breadcrumbSpans.eq(0).text()).toBe('Early Access documentation')
+      expect($breadcrumbSpans.eq(1).text()).toBe('GitHub.com')
+      expect($breadcrumbLinks.eq(0).attr('title')).toBe('category: Enforcing best practices with GitHub Policies')
+      expect($breadcrumbLinks.eq(1).attr('title')).toBe('article: About GitHub Policies')
+      expect($breadcrumbLinks.eq(1).hasClass('text-gray-light')).toBe(true)
+    })
+  })
+
   describe('context.breadcrumbs object', () => {
     test('works on product index pages', async () => {
       const breadcrumbs = await getJSON('/en/github?json=breadcrumbs')