Merge branch 'main' of github.com:github/docs-internal into deprecate-2.19

sarahs · sarahs · commit ed9f804ed69c · 2020-11-17T13:37:33.000-05:00
diff --git a/javascripts/dev-toc.js b/javascripts/dev-toc.js
@@ -0,0 +1,39 @@
+const expandText = 'Expand All'
+const closeText = 'Close All'
+
+export default function devToc () {
+  const expandButton = document.querySelector('.js-expand')
+  if (!expandButton) return
+
+  const detailsElements = document.querySelectorAll('details')
+
+  expandButton.addEventListener('click', () => {
+    // on click, toggle all the details elements open or closed
+    const anyDetailsOpen = Array.from(detailsElements).find(details => details.open)
+
+    for (const detailsElement of detailsElements) {
+      anyDetailsOpen
+        ? detailsElement.removeAttribute('open')
+        : detailsElement.open = true
+    }
+
+    // toggle the button text on click
+    anyDetailsOpen
+      ? expandButton.textContent = expandText
+      : expandButton.textContent = closeText
+  })
+
+  // also toggle the button text on clicking any of the details elements
+  for (const detailsElement of detailsElements) {
+    detailsElement.addEventListener('click', () => {
+      expandButton.textContent = closeText
+
+      // we can only get an accurate count of the open details elements if we wait a fraction after click
+      setTimeout(() => {
+        if (!Array.from(detailsElements).find(details => details.open)) {
+          expandButton.textContent = expandText
+        }
+      }, 50)
+    })
+  }
+}
diff --git a/javascripts/events.js b/javascripts/events.js
@@ -192,6 +192,8 @@ export default function initializeEvents () {
     })
   })
 
+  if (!document.querySelector('.sidebar-products')) return
+
   // Navigate event
   Array.from(
     document.querySelectorAll('.sidebar-products details')
diff --git a/javascripts/index.js b/javascripts/index.js
@@ -16,6 +16,7 @@ import { fillCsrf } from './get-csrf'
 import initializeEvents from './events'
 import filterCodeExamples from './filter-code-examples'
 import allArticles from './all-articles'
+import devToc from './dev-toc'
 
 document.addEventListener('DOMContentLoaded', async () => {
   displayPlatformSpecificContent()
@@ -27,11 +28,12 @@ document.addEventListener('DOMContentLoaded', async () => {
   wrapCodeTerms()
   print()
   localization()
-  await fillCsrf() // this must complete before any POST calls
-  helpfulness()
-  experiment()
   copyCode()
-  initializeEvents()
   filterCodeExamples()
   allArticles()
+  devToc()
+  await fillCsrf() // this must complete before any POST calls
+  initializeEvents() // requires fillCsrf to complete
+  experiment() // requires fillCsrf to complete
+  helpfulness() // requires fillCsrf to complete
 })
diff --git a/javascripts/nav.js b/javascripts/nav.js
@@ -3,6 +3,8 @@ export default function () {
   const hamburgerButton = document.querySelector('.nav-mobile-burgerIcon')
   const mobileDropdown = document.querySelector('.nav-mobile-dropdown')
 
+  if (!(hamburgerButton && mobileDropdown)) return
+
   hamburgerButton.addEventListener('click', (event) => {
     event.preventDefault()
     hamburgerButton.classList.toggle('js-open')
diff --git a/javascripts/search.js b/javascripts/search.js
@@ -63,6 +63,8 @@ const resultTemplate = (item) => {
 }
 
 export default function () {
+  if (!document.querySelector('#search-results-container')) return
+
   window.initialPageLoad = true
   const opts = {
 
diff --git a/layouts/dev-toc.html b/layouts/dev-toc.html
@@ -0,0 +1,82 @@
+<!doctype html>
+<html lang="{{currentLanguage}}">
+<head>
+<meta charset="utf-8" />
+<title>Docs TOC</title>
+<link rel="stylesheet" href="/dist/index.css">
+<link rel="alternate icon" type="image/png" href="/assets/images/site/favicon.png">
+<link rel="icon" type="image/svg+xml" href="/assets/images/site/favicon.svg">
+</head>
+  
+<body class="dev-toc p-3 m-3">
+<main class="width-full">
+
+<h3>Versions</h3>
+<ul class="versions-list">
+{% for version in allVersions %}
+<li><a href="/{{ version[0] }}/dev-toc">{{ version[1].versionTitle }}</a>
+{% endfor %}
+</ul>
+
+{% if allVersions[currentVersion] %}
+<h2 class="mt-3 mb-3"><abbr>TOC</abbr> for {{ allVersions[currentVersion].versionTitle }}</h2>
+
+<button class="btn mb-3 js-expand" type="button">Expand All</button>
+<div/>
+
+{% for product in siteTree[currentLanguage][currentVersion].products %}
+<details class="mb-1"><summary>{{product[1].title}}</summary>
+<ul class="products-list">
+<li title="{{product[1].title}}">
+  <a href="/{{currentLanguage}}{{product[1].href}}">{{ product[1].title }}</a>
+  {% for category in product[1].categories %}
+  {% capture fullPathToCategory %}/{{currentLanguage}}{{category[1].href}}{% endcapture %}
+  <ul>
+  <li>
+    <a href="{{fullPathToCategory}}">{{ category[1].title }}</a>
+      <!-- some categories have maptopics with child articles -->
+      {% if category[1].maptopics %}
+      <ul">
+        {% for maptopic in category[1].maptopics %}
+          {% unless maptopic[1].hidden %}
+            {% capture fullPathToMaptopic %}/{{currentLanguage}}{{maptopic[1].href}}{% endcapture %}
+
+            <li>
+              <a href="{{fullPathToMaptopic}}">{{ maptopic[1].title }}</a>
+              <ul>
+                {% for article in maptopic[1].articles %}
+                {% capture fullPathToArticle %}/{{currentLanguage}}{{article[1].href}}{% endcapture %}
+
+                <li>
+                  <a href="{{fullPathToArticle}}">{{ article[1].title }}</a>
+                </li>
+                {% endfor %}
+              </ul>
+            </li>
+          {% endunless %}
+        {% endfor %}
+      </ul>
+      <!-- some categories have no maptopics, only articles -->
+      {% else %}
+      <ul>
+        {% for article in category[1].articles %}
+        {% capture fullPathToArticle %}/{{currentLanguage}}{{article[1].href}}{% endcapture %}
+        <li>
+          <a href="{{fullPathToArticle}}">{{ article[1].title }}</a>
+        </li>
+        {% endfor %}
+      </ul>
+      {% endif %}
+  </li>
+  {% endfor %}
+</ul>
+</li>
+</ul>
+</details>
+{% endfor %}
+{% endif %}
+
+{% include scripts %}
+</main>
+</body>
+</html>
diff --git a/middleware/dev-toc.js b/middleware/dev-toc.js
@@ -0,0 +1,9 @@
+const { liquid } = require('../lib/render-content')
+const layouts = require('../lib/layouts')
+
+module.exports = async (req, res, next) => {
+  if (process.env.NODE_ENV !== 'development') return next()
+  if (!req.path.endsWith('/dev-toc')) return next()
+
+  return res.send(await liquid.parseAndRender(layouts['dev-toc'], req.context))
+}
diff --git a/middleware/enterprise-homepage.js b/middleware/enterprise-homepage.js
diff --git a/middleware/homepages.js b/middleware/homepages.js
diff --git a/middleware/index.js b/middleware/index.js
@@ -10,52 +10,73 @@ const asyncMiddleware = fn =>
   }
 
 module.exports = function (app) {
+  // *** Development tools ***
+  app.use(require('morgan')('dev', { skip: (req, res) => !isDevelopment }))
+  if (isDevelopment) app.use(require('./webpack'))
+
+  // *** Early exits ***
   // Don't use the proxy's IP, use the requester's for rate limiting
   // See https://expressjs.com/en/guide/behind-proxies.html
   app.set('trust proxy', 1)
-  app.use(require('morgan')('dev', { skip: (req, res) => !isDevelopment }))
   app.use(require('./rate-limit'))
-  if (isDevelopment) app.use(require('./webpack'))
-  app.use(require('./cookie-parser'))
-  app.use(require('./req-utils'))
-  app.use(require('./record-redirect'))
-  app.use(require('./redirects/external'))
-  app.use(require('./redirects/help-to-docs'))
-  app.use(require('./set-fastly-cache-headers'))
   app.use(require('./handle-invalid-paths'))
-  app.use(require('./loaderio-verification'))
+
+  // *** Security ***
   app.use(require('./cors'))
-  app.use(require('./csp'))
+  app.use(require('./csp')) // Must come before helmet
   app.use(require('helmet')())
-  app.use(require('./robots'))
-  app.use(express.json()) // Must come before ./csrf
+  app.use(require('./cookie-parser')) // Must come before csrf
+  app.use(express.json()) // Must come before csrf
   app.use(require('./csrf'))
-  app.use(require('./handle-csrf-errors'))
+  app.use(require('./handle-csrf-errors')) // Must come before regular handle-errors
+
+  // *** Headers ***
   app.use(require('compression')())
+  app.use(require('./set-fastly-cache-headers'))
+  app.use(require('./disable-caching-on-safari'))
+
+  // *** Config and context for redirects ***
+  app.use(require('./req-utils')) // Must come before record-redirect and events
+  app.use(require('./record-redirect'))
+  app.use(require('./detect-language')) // Must come before context, breadcrumbs, find-page, handle-errors, homepages
+  app.use(asyncMiddleware(require('./context'))) // Must come before early-access-*, handle-redirects
+
+  // *** Redirects, 3xx responses ***
+  // I ordered these by use frequency
   app.use(require('connect-slashes')(false))
+  app.use(require('./redirects/external'))
+  app.use(require('./redirects/help-to-docs'))
+  app.use(require('./redirects/language-code-redirects')) // Must come before contextualizers
+  app.use(require('./redirects/handle-redirects')) // Must come before contextualizers
+
+  // *** Config and context for rendering ***
+  app.use(require('./find-page')) // Must come before archived-enterprise-versions, breadcrumbs, featured-links, products, render-page
+
+  // *** Rendering, 2xx responses ***
+  // I largely ordered these by use frequency
+  app.use(require('./archived-enterprise-versions-assets')) // Must come before static/assets
   app.use('/dist', express.static('dist'))
+  app.use('/assets', express.static('assets'))
+  app.use('/public', express.static('data/graphql'))
   app.use('/events', require('./events'))
-  app.use(require('./categories-for-support-team'))
-  app.use(require('./detect-language'))
-  app.use(asyncMiddleware(require('./context')))
   app.use('/csrf', require('./csrf-route'))
+  app.use(require('./archived-enterprise-versions'))
+  app.use(require('./robots'))
   app.use(require('./early-access-paths'))
   app.use(require('./early-access-proxy'))
-  app.use(require('./find-page'))
-  app.use(require('./archived-enterprise-versions'))
-  app.use(require('./archived-enterprise-versions-assets'))
-  app.use('/assets', express.static('assets'))
-  app.use('/public', express.static('data/graphql'))
-  app.use(require('./redirects/language-code-redirects'))
-  // redirects need to be handled before the contextualizers
-  app.use(require('./redirects/handle-redirects'))
+  app.use(require('./categories-for-support-team'))
+  app.use(require('./loaderio-verification'))
+  app.get('/_500', asyncMiddleware(require('./trigger-error')))
+
+  // *** Preparation for render-page ***
   app.use(require('./contextualizers/graphql'))
   app.use(require('./contextualizers/rest'))
   app.use(require('./contextualizers/webhooks'))
-  app.use(require('./disable-caching-on-safari'))
-  app.get('/_500', asyncMiddleware(require('./trigger-error')))
   app.use(require('./breadcrumbs'))
+  app.use(require('./dev-toc'))
   app.use(require('./featured-links'))
+
+  // *** Rendering, must go last ***
   app.get('/*', asyncMiddleware(require('./render-page')))
   app.use(require('./handle-errors'))
 }
diff --git a/middleware/products.js b/middleware/products.js
diff --git a/stylesheets/dev-toc.scss b/stylesheets/dev-toc.scss
@@ -0,0 +1,14 @@
+/* Styles used for top-level TOC in development only
+------------------------------------------------------------------------------*/
+
+ul.versions-list {
+  list-style-type: none;
+}
+
+ul.versions-list > li {
+  margin: 3px 0 0 0;
+}
+
+details ul.products-list li {
+  margin: 3px 0 0 30px;
+}
diff --git a/stylesheets/index.scss b/stylesheets/index.scss
@@ -55,3 +55,4 @@ $marketing-font-path: "/dist/fonts/";
 @import "print.scss";
 @import "shadows.scss";
 @import "product-landing.scss";
+@import "dev-toc.scss";

Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,8 @@ const resultTemplate = (item) => {`
`63`	`63`	`}`
`64`	`64`
`65`	`65`	`export default function () {`
	`66`	`+ if (!document.querySelector('#search-results-container')) return`
	`67`	`+`
`66`	`68`	`window.initialPageLoad = true`
`67`	`69`	`const opts = {`
`68`	`70`