diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 4a8c5893..e93a1968 100644 --- 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 index 1a2dfe39..f5b0f1f3 100644 --- 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 index 917390ea..bb1b7eb7 100644 --- 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 index 532e6fe5..9e6f5c60 100644 --- 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 index 94b3502f..71500f93 100644 --- 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 index 2e0a37e5..e5f26753 100644 --- 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 index fcfd42a9..ed1433e3 100644 --- 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 index 88c52b95..d9e3bf02 100644 --- 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 index b369c9bd..91c859f6 100644 --- 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 index 170487fb..ace56641 100644 --- 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 index b07ab007..2e0c52ac 100644 --- 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/README.md b/analyses/0008-backstage/index.md similarity index 100% rename from analyses/0008-backstage/README.md rename to analyses/0008-backstage/index.md diff --git a/analyses/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md index e749f483..d44fd819 100644 --- 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 index a7fd243c..be8d5b5f 100644 --- 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 index b4a31636..fdc94a0a 100644 --- 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 index b5b9c082..68f15f00 100644 --- 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/README.md b/analyses/0009-in-toto/index.md similarity index 98% rename from analyses/0009-in-toto/README.md rename to analyses/0009-in-toto/index.md index 5367d5f7..818c644f 100644 --- a/analyses/0009-in-toto/README.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 index 55fb1fef..b9903c85 100644 --- 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/README.md b/analyses/0010-etcd/index.md similarity index 100% rename from analyses/0010-etcd/README.md rename to analyses/0010-etcd/index.md diff --git a/analyses/0011-keda/README.md b/analyses/0011-keda/index.md similarity index 100% rename from analyses/0011-keda/README.md rename to analyses/0011-keda/index.md diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/index.md similarity index 96% rename from analyses/0012-TUF/README.md rename to analyses/0012-TUF/index.md index 72552258..81e3de60 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/index.md @@ -1,4 +1,5 @@ --- +title: TUF Documentation Analysis cSpell:ignore: theupdateframework --- diff --git a/analyses/README.md b/analyses/index.md similarity index 98% rename from analyses/README.md rename to analyses/index.md index e8fa04b3..e4c9eae5 100644 --- a/analyses/README.md +++ b/analyses/index.md @@ -1,3 +1,7 @@ +--- +title: TechDocs Analysis for CNCF Projects +--- + # TechDocs Analysis for CNCF Projects diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 8ce51070..9045bb01 100644 --- 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 index aea4e93e..19a71825 100644 --- 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/README.md b/docs/analysis/index.md similarity index 87% rename from docs/analysis/README.md rename to docs/analysis/index.md index 195a967a..fd73d1c6 100644 --- a/docs/analysis/README.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/README.md b/docs/analysis/templates/index.md similarity index 94% rename from docs/analysis/templates/README.md rename to docs/analysis/templates/index.md index 164e4107..0865fb05 100644 --- a/docs/analysis/templates/README.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/README.md b/docs/analytics/index.md similarity index 97% rename from docs/analytics/README.md rename to docs/analytics/index.md index cc198c77..9567cbb0 100644 --- a/docs/analytics/README.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 index 79733efc..3855f905 100644 --- 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 index 53626578..cbbd3097 100644 --- 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 index 49155341..2ff580cf 100644 --- 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/README.md b/docs/index.md similarity index 80% rename from docs/README.md rename to docs/index.md index 9eec0117..806cabdf 100644 --- a/docs/README.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/README.md b/docs/localization/index.md similarity index 92% rename from docs/localization/README.md rename to docs/localization/index.md index b7aee9c9..b5604341 100644 --- a/docs/localization/README.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/README.md b/docs/localization/ja/index.md similarity index 98% rename from docs/localization/ja/README.md rename to docs/localization/ja/index.md index 2a47790c..442cae0e 100644 --- a/docs/localization/ja/README.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 index 94351d4e..f8591709 100644 --- 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 index e58fb202..bf7003c3 100644 --- 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 index 43c6a631..f95e8e76 100644 --- 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 index c137ad25..539141e4 100644 --- a/docs/searching-documentation.md +++ b/docs/searching-documentation.md @@ -1,3 +1,7 @@ +--- +title: Documentation Search +--- + # Documentation Search diff --git a/docs/services.md b/docs/services.md index 5d91e4f5..455d3219 100644 --- 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 index 2a17b221..91aafde6 100644 --- 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 index 685a4f6e..936b1d24 100644 --- 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 new file mode 100644 index 00000000..933f5295 --- /dev/null +++ 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();