Function mergeWithManualContent

scripts/generate-docs.ts:2663–2706

(
  generatedMarkdown: string,
  existingContent: string | null,
  manualSections: Record<string, string>
)

}

function mergeWithManualContent(
  generatedMarkdown: string,
  existingContent: string | null,
  manualSections: Record<string, string>
): string {
  if (!existingContent || Object.keys(manualSections).length === 0) {
    return generatedMarkdown
  }

  let mergedContent = generatedMarkdown

  Object.entries(manualSections).forEach(([sectionName, content]) => {
    const insertionPoints: Record<string, { regex: RegExp }> = {
      intro: {
        regex: /<BlockInfoCard[\s\S]*?(\/>|<\/svg>`}\s*\/>)/,
      },
      usage: {
        regex: /## Usage Instructions/,
      },
      outputs: {
        regex: /## Outputs/,
      },
      notes: {
        regex: /## Notes/,
      },
    }

    const insertionPoint = insertionPoints[sectionName]
    const wrapped = `{/* MANUAL-CONTENT-START:${sectionName} */}\n${content}\n{/* MANUAL-CONTENT-END */}`

    const match = insertionPoint ? mergedContent.match(insertionPoint.regex) : null
    if (match && match.index !== undefined) {
      const insertPosition = match.index + match[0].length
      mergedContent = `${mergedContent.slice(0, insertPosition)}\n\n${wrapped}\n${mergedContent.slice(insertPosition)}`
    } else {
      // Never drop manual content: when the anchor is missing (e.g. a `notes`
      // section with no generated "## Notes" heading), append at the end.
      console.log(`No insertion anchor for manual section "${sectionName}" — appending at end`)
      mergedContent = `${mergedContent.replace(/\s*$/, '')}\n\n${wrapped}\n`
    }
  })

  return mergedContent
}

async function generateBlockDoc(blockPath: string) {
  try {