Rename {analyses,docs}/**/README.md to index.md (#323)

chalin · web-flow · commit 97a0fffdfd27 · 2025-06-16T14:07:26.000-04:00
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -4,3 +4,4 @@
 list-marker-space: false
 no-inline-html: false
 no-bare-urls: false
+single-h1: false # Temporary
diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md
@@ -1,4 +1,5 @@
 ---
+title: Docs assessment
 cSpell:ignore: Horgan celestehorgan hashlinks
 ---
 
diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md
@@ -1,4 +1,5 @@
 ---
+title: Notary Project Docs Assessment
 cSpell:ignore: docset notaryproject celestehorgan
 ---
 
diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md
@@ -1,4 +1,5 @@
 ---
+title: Krator Docs assessment
 cSpell:ignore: Krator celestehorgan CODEOWNERS
 ---
 
diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md
@@ -1,4 +1,5 @@
 ---
+title: 'Assessment: Project Tremor'
 cSpell:ignore: Horgan onramps offramps LLDB Wayfair
 ---
 
diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md
@@ -1,4 +1,5 @@
 ---
+title: Assessment template
 cSpell:ignore: celestehorgan Horgan
 ---
 
diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md
@@ -1,4 +1,5 @@
 ---
+title: 'Assessment: Project Kubernetes Gateway API'
 cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes
 ---
 
diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md
@@ -1,4 +1,5 @@
 ---
+title: Porter Docs Analysis
 cSpell:ignore: Uchechukwu Obasi
 ---
 
diff --git a/analyses/0008-backstage/backstage-glossary.md b/analyses/0008-backstage/backstage-glossary.md
@@ -1,3 +1,7 @@
+---
+title: Backstage Glossary
+---
+
 # Backstage Glossary
 
 ## API
diff --git a/analyses/0008-backstage/backstage-insights-summary.md b/analyses/0008-backstage/backstage-insights-summary.md
@@ -1,4 +1,5 @@
 ---
+title: Backstage Insights
 cSpell:ignore: flipside
 ---
 
diff --git a/analyses/0008-backstage/backstage-issues.md b/analyses/0008-backstage/backstage-issues.md
@@ -1,3 +1,7 @@
+---
+title: Backstage umbrella issue
+---
+
 # Backstage umbrella issue
 
 ## Overview
diff --git a/analyses/0008-backstage/index.md b/analyses/0008-backstage/index.md
diff --git a/analyses/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md
@@ -1,3 +1,7 @@
+---
+title: Backstage User Roles for Doc
+---
+
 # Backstage User Roles for Doc
 
 This document provides recommendations for user roles, or personas, for
diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md
@@ -1,3 +1,7 @@
+---
+title: Analysis of Existing Documentation
+---
+
 # Analysis of Existing Documentation
 
 This document characterizes the effectiveness and completeness of the in-toto
diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md
@@ -1,3 +1,7 @@
+---
+title: Documentation Issues
+---
+
 # Documentation Issues
 
 These issues identify and classify tasks that contributors can undertake to
diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md
@@ -1,4 +1,5 @@
 ---
+title: Implementation
 cSpell:ignore: roadmaps Cappos
 ---
 
diff --git a/analyses/0009-in-toto/index.md b/analyses/0009-in-toto/index.md
@@ -1,3 +1,7 @@
+---
+title: README
+---
+
 # README
 
 These documents are intended to recommend a direction for the ongoing
diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md
@@ -1,3 +1,7 @@
+---
+title: Survey of existing documentation as of 09/2023
+---
+
 # Survey of existing documentation as of 09/2023
 
 The following links are loosely sorted into conceptual categories.
diff --git a/analyses/0010-etcd/index.md b/analyses/0010-etcd/index.md
diff --git a/analyses/0011-keda/index.md b/analyses/0011-keda/index.md
diff --git a/analyses/0012-TUF/index.md b/analyses/0012-TUF/index.md
@@ -1,4 +1,5 @@
 ---
+title: TUF Documentation Analysis
 cSpell:ignore: theupdateframework
 ---
 
diff --git a/analyses/index.md b/analyses/index.md
@@ -1,3 +1,7 @@
+---
+title: TechDocs Analysis for CNCF Projects
+---
+
 <!-- cSpell:ignore projectname -->
 
 # TechDocs Analysis for CNCF Projects
diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md
@@ -1,3 +1,7 @@
+---
+title: Assessment criteria and examples
+---
+
 # Assessment criteria and examples
 
 We recommend reading the
diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md
@@ -1,3 +1,7 @@
+---
+title: CNCF TechDocs Analysis How-To
+---
+
 # CNCF TechDocs Analysis How-To
 
 ## Audience
@@ -217,5 +221,5 @@ Create issues in the project documentation GitHub repository for:
 [analyses]: ../../analyses/
 [criteria]: ./criteria.md
 [project maturity level]: https://www.cncf.io/project-metrics
-[templates]: ./templates/README.md
+[templates]: ./templates/index.md
 [issues list]: ./templates/issues-list.md
diff --git a/docs/analysis/index.md b/docs/analysis/index.md
@@ -1,3 +1,7 @@
+---
+title: TechDoc Analysis
+---
+
 # TechDoc Analysis
 
 This section contains instructions and criteria for completing a documentation
diff --git a/docs/analysis/templates/index.md b/docs/analysis/templates/index.md
@@ -1,3 +1,7 @@
+---
+title: TechDoc Analysis Templates
+---
+
 # TechDoc Analysis Templates
 
 This section contains templates for analyzing a CNCF project's documentation.
diff --git a/docs/analytics/index.md b/docs/analytics/index.md
@@ -1,3 +1,7 @@
+---
+title: Analytics
+---
+
 # Analytics
 
 ## Google Analytics
diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md
@@ -1,4 +1,5 @@
 ---
+title: Migrating Universal to Google Analytics 4
 cSpell:ignore: gtag kubernetes
 ---
 
diff --git a/docs/assistance.md b/docs/assistance.md
@@ -1,3 +1,7 @@
+---
+title: Assistance program for technical documentation
+---
+
 # Assistance program for technical documentation
 
 This document outlines the Cloud Native Computing Foundation (CNCF) Technical
diff --git a/docs/hugo-and-docsy.md b/docs/hugo-and-docsy.md
@@ -1,3 +1,7 @@
+---
+title: Hugo and Docsy
+---
+
 # Hugo and Docsy
 
 Tips:
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,8 @@
+---
+title: CNCF Techdocs how-tos
+sidebar_position: 1
+---
+
 # CNCF Techdocs how-tos
 
 This directory contains documentation on how the CNCF TechDocs team does things.
diff --git a/docs/localization/index.md b/docs/localization/index.md
@@ -1,3 +1,7 @@
+---
+title: CNCF Localization Guides
+---
+
 # CNCF Localization Guides
 
 This directory contains a growing collection of localization guides that CNCF
diff --git a/docs/localization/ja/index.md b/docs/localization/ja/index.md
@@ -1,3 +1,7 @@
+---
+title: CNCF日本語ローカライゼーション向けガイドライン
+---
+
 # CNCF日本語ローカライゼーション向けガイドライン
 
 このドキュメントでは、CNCFのプロジェクトをローカライズする際に参考になる一般的なガイドラインを提供します。
diff --git a/docs/netlify-domains-setup.md b/docs/netlify-domains-setup.md
@@ -1,4 +1,5 @@
 ---
+title: Netlify and domain setup
 cSpell:ignore: caniszczyk
 ---
 
diff --git a/docs/repo-setup.md b/docs/repo-setup.md
@@ -1,4 +1,5 @@
 ---
+title: Repository setup
 cSpell:ignore: cncf
 ---
 
diff --git a/docs/sandbox-doc-primer.md b/docs/sandbox-doc-primer.md
@@ -1,3 +1,7 @@
+---
+title: CNCF sandbox project documentation primer
+---
+
 # CNCF sandbox project documentation primer
 
 This document is a quick primer for CNCF project maintainers and contributors
diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md
@@ -1,3 +1,7 @@
+---
+title: Documentation Search
+---
+
 # Documentation Search
 
 <!-- markdownlint-disable no-duplicate-heading -->
diff --git a/docs/services.md b/docs/services.md
@@ -1,3 +1,7 @@
+---
+title: Services for projects
+---
+
 # Services for projects
 
 The CNCF provides technical writing and documentation website services for all
diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md
@@ -1,4 +1,5 @@
 ---
+title: prettier-ignore
 # prettier-ignore
 cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi
 ---
diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md
@@ -1,3 +1,7 @@
+---
+title: CNCF website guidelines checklist
+---
+
 # CNCF website guidelines checklist
 
 As per the
diff --git a/scripts/add-frontmatter.mjs b/scripts/add-frontmatter.mjs
@@ -0,0 +1,100 @@
+import { readFile, writeFile } from 'fs/promises';
+import { glob } from 'glob';
+import path from 'path';
+
+// Regular expression to match frontmatter
+const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+
+// Regular expression to match first heading
+const headingRegex = /^#\s+(.+)$/m;
+
+// Regular expression to match title in frontmatter
+const titleRegex = /^title:\s*(.+)$/m;
+
+async function processFile(filePath) {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const headingMatch = content.match(headingRegex);
+
+    if (!headingMatch) {
+      console.log(`Warning: ${filePath} has no heading to use as title`);
+      return;
+    }
+
+    const headingTitle = headingMatch[1].trim();
+    let hasFrontmatter = false;
+    let existingTitle = null;
+    let contentWithoutFrontmatter = content;
+    let existingFrontmatter = '';
+
+    // Check for existing frontmatter
+    const frontmatterMatch = content.match(frontmatterRegex);
+    if (frontmatterMatch) {
+      hasFrontmatter = true;
+      existingFrontmatter = frontmatterMatch[1];
+      contentWithoutFrontmatter = content.slice(frontmatterMatch[0].length);
+
+      // Check if title already exists
+      const titleMatch = existingFrontmatter.match(titleRegex);
+      if (titleMatch) {
+        existingTitle = titleMatch[1].trim();
+      }
+    }
+
+    // Only update if:
+    // 1. No frontmatter exists, or
+    // 2. Frontmatter exists but has no title, or
+    // 3. Frontmatter title doesn't match the heading
+    const needsUpdate = !hasFrontmatter || !existingTitle;
+    // || existingTitle !== headingTitle
+    if (needsUpdate) {
+      let newFrontmatter;
+      const formattedTitle = headingTitle.includes(':')
+        ? `'${headingTitle}'`
+        : headingTitle;
+      if (hasFrontmatter) {
+        // Remove existing title if it exists
+        const frontmatterWithoutTitle = existingFrontmatter
+          .replace(titleRegex, '')
+          .trim();
+        newFrontmatter = `title: ${formattedTitle}${frontmatterWithoutTitle ? '\n' + frontmatterWithoutTitle : ''}`;
+      } else {
+        newFrontmatter = `title: ${formattedTitle}`;
+      }
+
+      const newContent = `---
+${newFrontmatter}
+---\n
+${contentWithoutFrontmatter}`;
+
+      await writeFile(filePath, newContent);
+      console.log(
+        `${hasFrontmatter ? 'Updated' : 'Added'} frontmatter to ${filePath}`,
+      );
+    } else {
+      console.log(`Skipping ${filePath} - frontmatter title matches heading`);
+    }
+  } catch (error) {
+    console.error(`Error processing ${filePath}:`, error);
+  }
+}
+
+async function main() {
+  try {
+    // Find all markdown files in docs directory
+    const files = await glob('{analyses,docs}/**/*.md');
+    console.log(`Found ${files.length} markdown files`);
+
+    // Process each file
+    for (const file of files) {
+      await processFile(file);
+    }
+
+    console.log('Done!');
+  } catch (error) {
+    console.error('Error:', error);
+    process.exit(1);
+  }
+}
+
+main();
