Add README project index generation

Add automatic generation and updating of a Projects section in the repository README. scripts/generate.js: introduce constants for generated section markers, buildProjectDirectoryUrl, generateRootProjectIndex and updateRootReadme to insert or replace a generated list of project links; call updateRootReadme from main using listProjectDirectories. Also refactor generateProjectReadme to use encoded manifest URLs and markdown-style links for project READMEs. Update README.md to include the generated Projects section and convert example-project/README.md links to markdown format so they match the generated output.

Author: cubap

README.md

@@ -29,6 +29,12 @@ This repository is designed for low-friction manifest creation:
 └── .github/workflows/generate-manifests.yml
 ```
 
+<!-- GENERATED_PROJECT_LINKS_START -->
+## Projects
+
+- [example-project](./projects/example-project/)
+<!-- GENERATED_PROJECT_LINKS_END -->
+
 ## Project Inputs
 
 Each project lives in `projects/{project-name}`.

projects/example-project/README.md

@@ -12,11 +12,11 @@ This project is generated by repository scripts.
 - WARNING.md
 
 ## Links
-- Manifest: https://CenterForDigitalHumanities.github.io/Github-Manifests/projects/example-project/manifest.json
-- Images folder: ./images/
-- Mirador: https://projectmirador.org/embed/?iiif-content=https://CenterForDigitalHumanities.github.io/Github-Manifests/projects/example-project/manifest.json
-- Universal Viewer: https://uv-v3.netlify.app/#?manifest=https://CenterForDigitalHumanities.github.io/Github-Manifests/projects/example-project/manifest.json
-- TPEN3 Import: https://app.t-pen.org/project/import?manifest=https%3A%2F%2FCenterForDigitalHumanities.github.io%2FGithub-Manifests%2Fprojects%2Fexample-project%2Fmanifest.json
+- [Manifest](https://CenterForDigitalHumanities.github.io/Github-Manifests/projects/example-project/manifest.json)
+- [Images folder](./images/)
+- [Mirador](https://projectmirador.org/embed/?iiif-content=https%3A%2F%2FCenterForDigitalHumanities.github.io%2FGithub-Manifests%2Fprojects%2Fexample-project%2Fmanifest.json)
+- [Universal Viewer](https://uv-v3.netlify.app/#?manifest=https%3A%2F%2FCenterForDigitalHumanities.github.io%2FGithub-Manifests%2Fprojects%2Fexample-project%2Fmanifest.json)
+- [TPEN3 Import](https://app.t-pen.org/project/import?manifest=https%3A%2F%2FCenterForDigitalHumanities.github.io%2FGithub-Manifests%2Fprojects%2Fexample-project%2Fmanifest.json)
 
 ## TPEN3
 Use the TPEN3 import link above to create a new project directly from this manifest.

scripts/generate.js

@@ -26,6 +26,9 @@ import {
   writeText
 } from "./utils.js"
 
+const ROOT_PROJECT_INDEX_START = "<!-- GENERATED_PROJECT_LINKS_START -->"
+const ROOT_PROJECT_INDEX_END = "<!-- GENERATED_PROJECT_LINKS_END -->"
+
 function createWarning(code, message, details = {}) {
   return {
     code,
@@ -132,6 +135,10 @@ function buildImageUrl(siteBaseUrl, projectName, imageRelativePath) {
   return `${siteBaseUrl}/projects/${projectName}/${toPosixPath(imageRelativePath)}`
 }
 
+function buildProjectDirectoryUrl(projectName) {
+  return `./projects/${projectName}/`
+}
+
 function normalizeTopLevelFields(info, warnings) {
   const out = {}
 
@@ -669,9 +676,45 @@ function buildManifest({ projectName, siteBaseUrl, info, resources, warnings })
 }
 
 function generateProjectReadme(projectName, manifestUrl) {
-  const tpenImportUrl = `https://app.t-pen.org/project/import?manifest=${encodeURIComponent(manifestUrl)}`
+  const encodedManifestUrl = encodeURIComponent(manifestUrl)
+  const miradorUrl = `https://projectmirador.org/embed/?iiif-content=${encodedManifestUrl}`
+  const universalViewerUrl = `https://uv-v3.netlify.app/#?manifest=${encodedManifestUrl}`
+  const tpenImportUrl = `https://app.t-pen.org/project/import?manifest=${encodedManifestUrl}`
+
+  return `# ${projectName}\n\nThis project is generated by repository scripts.\n\n## Inputs\n- Add local images in images/\n- Add external references using .lnk files in images/ (one HTTP(S) URL per file)\n- Optional advanced configuration in info.yml\n\n## Generated Outputs\n- manifest.json\n- WARNING.md\n\n## Links\n- [Manifest.json](${manifestUrl})\n- [Images folder](./images/)\n- [Mirador Viewer](${miradorUrl})\n- [Universal Viewer](${universalViewerUrl})\n- [TPEN3 Create Project](${tpenImportUrl})\n\n## TPEN3\nUse the TPEN3 import link above to create a new project directly from this manifest.\n\n> This file is regenerated when manifest generation runs. Put durable custom metadata in info.yml.\n`
+}
+
+function generateRootProjectIndex(projectNames) {
+  const items = projectNames
+    .map((projectName) => `- [${projectName}](${buildProjectDirectoryUrl(projectName)})`)
+    .join("\n")
 
-  return `# ${projectName}\n\nThis project is generated by repository scripts.\n\n## Inputs\n- Add local images in images/\n- Add external references using .lnk files in images/ (one HTTP(S) URL per file)\n- Optional advanced configuration in info.yml\n\n## Generated Outputs\n- manifest.json\n- WARNING.md\n\n## Links\n- Manifest: ${manifestUrl}\n- Images folder: ./images/\n- Mirador: https://projectmirador.org/embed/?iiif-content=${manifestUrl}\n- Universal Viewer: https://uv-v3.netlify.app/#?manifest=${manifestUrl}\n- TPEN3 Import: ${tpenImportUrl}\n\n## TPEN3\nUse the TPEN3 import link above to create a new project directly from this manifest.\n\n> This file is regenerated when manifest generation runs. Put durable custom metadata in info.yml.\n`
+  return `${ROOT_PROJECT_INDEX_START}\n## Projects\n\n${items}\n${ROOT_PROJECT_INDEX_END}`
+}
+
+async function updateRootReadme(projectNames) {
+  const readmePath = path.join(repoRoot, "README.md")
+  const readme = await fs.readFile(readmePath, "utf8")
+  const generatedSection = generateRootProjectIndex(projectNames)
+  const existingSectionPattern = new RegExp(
+    `${ROOT_PROJECT_INDEX_START}[\\s\\S]*?${ROOT_PROJECT_INDEX_END}`,
+    "m"
+  )
+
+  if (existingSectionPattern.test(readme)) {
+    const updatedReadme = readme.replace(existingSectionPattern, generatedSection)
+    await writeText(readmePath, updatedReadme)
+    return
+  }
+
+  const insertionMarker = "## Project Inputs"
+  const insertionIndex = readme.indexOf(insertionMarker)
+  if (insertionIndex === -1) {
+    throw new Error("Could not find '## Project Inputs' section in README.md to insert project links.")
+  }
+
+  const updatedReadme = `${readme.slice(0, insertionIndex)}${generatedSection}\n\n${readme.slice(insertionIndex)}`
+  await writeText(readmePath, updatedReadme)
 }
 
 function generateWarningsMarkdown(projectName, warnings) {
@@ -765,6 +808,9 @@ async function main() {
     results.push(result)
   }
 
+  const allProjectNames = await listProjectDirectories(projectsRoot)
+  await updateRootReadme(allProjectNames)
+
   for (const result of results) {
     console.log(`Generated ${result.projectName} (warnings: ${result.warningCount})`)
   }