Merge pull request #29811 from github/dev-toc-scriptified

Reintroduce the dev TOC via a script

.gitignore

@@ -9,6 +9,7 @@ coverage/
 /assets/images/early-access
 /content/early-access
 /data/early-access
+/script/dev-toc/static
 .next
 .eslintcache
 *.tsbuildinfo

script/dev-toc/generate.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import { execSync } from 'child_process'
+import { program } from 'commander'
+import fpt from '../../lib/non-enterprise-default-version.js'
+import { allVersionKeys } from '../../lib/all-versions.js'
+import { liquid } from '../../lib/render-content/index.js'
+import contextualize from '../../middleware/context.js'
+
+const layoutFilename = path.posix.join(process.cwd(), 'script/dev-toc/layout.html')
+const layout = fs.readFileSync(layoutFilename, 'utf8')
+
+const staticDirName = 'script/dev-toc/static'
+const staticDir = path.posix.join(process.cwd(), staticDirName)
+if (!fs.existsSync(staticDir)) fs.mkdirSync(staticDir)
+
+program
+  .description('Generate a local TOC of the docs website and open it in your browser')
+  .option(
+    '-o, --openSections [product-ids...]',
+    'open sections for one or more product IDs by default (e.g., "-o codespaces pull-requests")'
+  )
+  .parse(process.argv)
+
+const options = program.opts()
+
+const openSections = options.openSections || ''
+const defaultOpenSections = Array.isArray(openSections) ? openSections : [openSections]
+
+main()
+
+async function main() {
+  const next = () => {}
+  const res = {}
+  const req = { language: 'en', cookies: {} }
+
+  for (const version of allVersionKeys) {
+    req.pagePath = version === fpt ? '/' : `/${version}`
+
+    // Create a subdir for the version if one doesn't exist yet.
+    const versionStaticDir = path.posix.join(staticDir, version)
+    if (!fs.existsSync(versionStaticDir)) fs.mkdirSync(versionStaticDir)
+
+    // Create a versioned filename.
+    const filename = path.posix.join(versionStaticDir, 'index.html')
+
+    // Create a minimal context object.
+    await contextualize(req, res, next)
+
+    // Add the tree to the req.context.
+    req.context.currentEnglishTree = req.context.siteTree.en[req.context.currentVersion]
+
+    // Add any defaultOpenSections to the context.
+    req.context.defaultOpenSections = defaultOpenSections
+
+    // Parse the layout in script/dev-toc/layout.html with the context we created above.
+    const outputHtml = await liquid.parseAndRender(layout, Object.assign({}, req.context))
+
+    // Write a static file for each version.
+    fs.writeFileSync(filename, outputHtml)
+  }
+
+  // Default to FPT for the file to open.
+  const fptFile = path.posix.join(staticDirName, fpt, 'index.html')
+
+  execSync(`open ${fptFile}`)
+
+  console.log(`\nCreated the TOC! If it doesn't open automatically, open the following file in your browser to view it:\n
+${fptFile}`)
+}

script/dev-toc/index.js

@@ -0,0 +1,41 @@
+const expandText = 'Expand All'
+const closeText = 'Close All'
+
+document.addEventListener('DOMContentLoaded', async () => {
+  devToc()
+})
+
+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)
+    })
+  }
+}

script/dev-toc/layout.html

@@ -0,0 +1,67 @@
+<!doctype html>
+<html lang="{{currentLanguage}}">
+<head>
+<meta charset="utf-8" />
+<title>Docs TOC</title>
+<link href="https://unpkg.com/@primer/css@^20.2.4/dist/primer.css" rel="stylesheet" />
+</head>
+
+<body class="dev-toc p-3 m-3">
+<main class="width-full">
+
+<h3>Versions</h3>
+<ul class="versions-list" style="list-style-type:none;">
+{% for version in allVersions %}
+<li style="margin: 3px 0 0 0;"><a href="../{{ version[0] }}/index.html">{{ version[1].versionTitle }}</a>
+{% endfor %}
+</ul>
+
+{% assign docsRoot = "https://docs.github.com" %}
+
+{% 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 productPage in currentEnglishTree.childPages %}
+{% assign productId = productPage.page.relativePath | replace: "/index.md", "" %}
+{% if defaultOpenSections contains productId %}
+<details open class="mb-1"><summary>{{productPage.renderedFullTitle}}</summary>
+{% else %}
+<details class="mb-1"><summary>{{productPage.renderedFullTitle}}</summary>
+{% endif %}
+<ul class="products-list">
+<li title="{{productPage.renderedFullTitle}}" style="margin: 3px 0 0 30px;">
+  <a title="{{ productPage.page.documentType }}" href="{{ docsRoot }}{{productPage.href}}">{{ productPage.renderedFullTitle }}</a>
+  {% for categoryPage in productPage.childPages %}
+  <ul>
+  <li style="margin: 3px 0 0 30px;">
+    <a title="{{ categoryPage.page.documentType }}" href="{{ docsRoot }}{{ categoryPage.href }}">{{ categoryPage.renderedFullTitle }}</a>
+      <ul>
+        {% for maptopicPage in categoryPage.childPages %}
+            <li style="margin: 3px 0 0 30px;">
+              <a title="{{ maptopicPage.page.documentType }}" href="{{ docsRoot }}{{ maptopicPage.href }}">{{ maptopicPage.renderedFullTitle }}</a>
+              <ul>
+                {% for articlePage in maptopicPage.childPages %}
+                <li style="margin: 3px 0 0 30px;">
+                  <a title="{{ articlePage.page.documentType }}" href="{{ docsRoot }}{{ articlePage.href }}">{{ articlePage.renderedFullTitle }}</a>
+                </li>
+                {% endfor %}
+              </ul>
+            </li>
+        {% endfor %}
+      </ul>
+  </li>
+  {% endfor %}
+</ul>
+</li>
+</ul>
+</details>
+{% endfor %}
+{% endif %}
+
+<script src="../../index.js"></script>
+</main>
+</body>
+</html>