functions/partials/addToDocsPages.mjsjavascript
import fs from 'node:fs'
import path from 'node:path'
import * as gulpConfig from '../../gulp.config.mjs'

// Every .html file below dirPath, at any depth
const listPages = dirPath => fs.readdirSync(dirPath, { withFileTypes: true })
  .flatMap(entry => {
    const entryPath = path.join(dirPath, entry.name)
    if (entry.isDirectory()) {
      return listPages(entryPath)
    }
    return entry.isFile() && /\.html?$/i.test(entry.name) ? [entryPath] : []
  })

// html with the snippet put just before the last closing tag of that name, or unchanged when it has none
const insertBefore = (html, tag, snippet) => {
  const at = html.toLowerCase().lastIndexOf(`</${tag}>`)
  return at === -1 ? html : `${html.slice(0, at)}${snippet}\n${html.slice(at)}`
}

/**
 * Add the HTML of docs.headHtml and docs.bodyHtml to every page of the generated documentation: the first just before
 * `</head>`, the second just before `</body>`, for example an analytics script the rest of the site has. Both engines
 * (TypeDoc and jsdoc) run it after generating, so a setting works the same with either. A setting left false adds
 * nothing, and a page without the tag is left as it is.
 * @memberOf module:partials
 * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation was generated into.
 * @param {string|false} [headHtml=gulpConfig.get('docs.headHtml')] - The HTML to add before `</head>`.
 * @param {string|false} [bodyHtml=gulpConfig.get('docs.bodyHtml')] - The HTML to add before `</body>`.
 * @returns {number} How many pages were changed.
 */
export const addToDocsPages = (
  outPath = gulpConfig.get('docs.to'),
  headHtml = gulpConfig.get('docs.headHtml'),
  bodyHtml = gulpConfig.get('docs.bodyHtml')
) => {
  if ((!headHtml && !bodyHtml) || !fs.existsSync(outPath)) {
    return 0
  }
  return listPages(outPath).reduce((changed, page) => {
    const html = fs.readFileSync(page, 'utf8')
    let updated = headHtml ? insertBefore(html, 'head', headHtml) : html
    updated = bodyHtml ? insertBefore(updated, 'body', bodyHtml) : updated
    if (updated === html) {
      return changed
    }
    fs.writeFileSync(page, updated)
    return changed + 1
  }, 0)
}