Merge branch 'main' into repo-sync

lib/get-mini-toc-items.js

@@ -35,6 +35,14 @@ export default function getMiniTocItems(html, maxHeadingLevel = 2, headingScope
       // Capture the anchor tag nested within the header, get its href and remove it
       const anchor = $('a.doctocat-link', item)
       const href = anchor.attr('href')
+      if (!href) {
+        // Can happen if the, for example, `<h2>` tag was put there
+        // manually with HTML into the Markdown content. Then it wouldn't
+        // be rendered with an expected `<a class="doctocat-link" href="#..."`
+        // link in front of it.
+        // The `return null` will be filtered after the `.map()`
+        return null
+      }
       anchor.remove()
 
       // remove any <strong> tags but leave content
@@ -52,6 +60,7 @@ export default function getMiniTocItems(html, maxHeadingLevel = 2, headingScope
 
       return { contents, headingLevel, platform }
     })
+    .filter(Boolean)
     .map((item) => {
       // set the indentation level for each item based on the most important
       // heading level in the current article

script/update-tocs.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+// [start-readme]
+//
+// This script creates or updates an index.md file for a given directory.
+// It will add `children` frontmatter in alphabetical order and create versions: '*'.
+// It also prints a helpful message to update those values manually if needed.
+//
+// [end-readme]
+
+import fs from 'fs'
+import path from 'path'
+import { sentenceCase } from 'change-case'
+import { program } from 'commander'
+import readFrontmatter from '../lib/read-frontmatter.js'
+
+program
+  .description('Create or update an index.md file for a provided content directory')
+  .requiredOption('-d, --directory <content directory>')
+  .parse(process.argv)
+
+const directory = path.posix.join(process.cwd(), program.opts().directory)
+
+if (!fs.existsSync(directory)) {
+  console.error(`Error! ${directory} not found. Make sure directory name starts with "content/".`)
+  process.exit(1)
+}
+
+// Run it! This function may run recursively.
+updateOrCreateToc(directory)
+
+console.log(
+  'Done! Review the new or updated index.md files and update the 1) order of the children 2) versions as needed'
+)
+
+function updateOrCreateToc(directory) {
+  const children = fs.readdirSync(directory).filter((subpath) => !subpath.endsWith('index.md'))
+  if (!children.length) return
+
+  const tocFile = path.posix.join(directory, 'index.md')
+
+  let content, data
+
+  // If the index.md file already exists, read it (to be updated later).
+  if (fs.existsSync(tocFile)) {
+    const parsed = readFrontmatter(fs.readFileSync(tocFile, 'utf8'))
+    content = parsed.content
+    data = parsed.data
+  }
+  // If the index.md file does not exist, create it.
+  else {
+    content = ''
+    data = {
+      title: sentenceCase(path.basename(directory)), // fake the title of the index.md from the directory name
+      versions: '*', // default to all versions
+    }
+  }
+
+  // Add the children - this will default to the alphabetical list of files in the directory.
+  data.children = children.map((child) => `/${child.replace('.md', '')}`)
+
+  // Write the file.
+  const newContents = readFrontmatter.stringify(content, data, { lineWidth: 10000 })
+  fs.writeFileSync(tocFile, newContents)
+
+  // Process any child directories recursively.
+  children.forEach((child) => {
+    if (child.endsWith('.md')) return
+    updateOrCreateToc(path.posix.join(directory, child))
+  })
+}

tests/unit/mini-toc-items.js

@@ -1,10 +1,24 @@
 import { expect } from '@jest/globals'
 import getMiniTocItems from '../../lib/get-mini-toc-items'
 
+// The getMiniTocItems() function requires that every <h2> and <h3>
+// contains a...
+//
+//   <a class="doctocat-link">
+//
+// tag within the tag. Having to manually put that into every HTML
+// snippet in each test is tediuous so this function makes it convenient.
+function injectDoctocatLinks(html) {
+  let counter = 0
+  return html.replace(/<h\d>/g, (m) => {
+    return `${m}\n<a href="#section${++counter}" class="doctocat-link">🔗</a>\n`
+  })
+}
+
 describe('mini toc items', () => {
   // Mock scenario from: /en/rest/reference/activity
   test('basic nested structure is created', async () => {
-    const html = `
+    const html = injectDoctocatLinks(`
       <body>
         <h1>Test</h1>
         <h2>Section 1</h2>
@@ -14,8 +28,9 @@ describe('mini toc items', () => {
         <h2>Section 2</h2>
         <h3>Section 2 A</h3>
       </body>
-    `
+    `)
     const tocItems = getMiniTocItems(html, 3)
+    expect(tocItems.length).toBe(2)
     expect(tocItems[0].items.length).toBe(3)
   })
 
@@ -31,15 +46,15 @@ describe('mini toc items', () => {
    *     3
    */
   test('creates toc that starts with lower importance headers', async () => {
-    const html = `
+    const html = injectDoctocatLinks(`
       <h1>Test</h1>
       <h3>Section 1 A</h3>
       <h3>Section 1 B</h3>
       <h2>Section 2</h2>
       <h3>Section 2 A</h3>
       <h2>Section 3</h2>
       <h3>Section 3 A</h3>
-    `
+    `)
     const tocItems = getMiniTocItems(html, 3)
     expect(tocItems.length).toBe(4)
     expect(tocItems[3].items.length).toBe(1)
@@ -56,26 +71,26 @@ describe('mini toc items', () => {
 
   // Mock scenario from: /en/repositories/creating-and-managing-repositories/about-repositories
   test('creates flat toc', async () => {
-    const html = `
+    const html = injectDoctocatLinks(`
       <h1>Test</h1>
       <h2>Section 1</h2>
       <h2>Section 2</h2>
-    `
+    `)
     const tocItems = getMiniTocItems(html, 3)
     expect(tocItems.length).toBe(2)
     expect(tocItems[0].items).toBeUndefined()
   })
 
   test('handles deeply nested toc', async () => {
-    const html = `
+    const html = injectDoctocatLinks(`
       <h1>Test</h1>
       <h2>Section 1</h2>
       <h2>Section 2</h2>
       <h3>Section 2 A</h3>
       <h4>Section 2 A 1</h4>
       <h5>Section 2 A 1 a</h5>
       <h2>Section 3</h2>
-    `
+    `)
     const tocItems = getMiniTocItems(html, 5)
     expect(tocItems.length).toBe(3)
     expect(tocItems[1].items[0].items[0].items.length).toBe(1)