Validate docs have a title: and fix for astro migration (microsoft#2561)

Astro requires every doc to have a title. Adding a simple script to
validate that so we don't have to patch things when migrating.

Author: timotheeguerin

docs/extending-typespec/diagnostics.md

@@ -1,4 +1,6 @@
-# Diagnostics
+---
+title: Diagnostics
+---
 
 TypeSpec compiler report errors and warnings in the spec using the diagnostic API.
 

docs/getting-started/getting-started-http.md

@@ -1,4 +1,6 @@
-# Getting Started with TypeSpec For Http
+---
+title: Getting Started with TypeSpec For Http
+---
 
 Let's create a REST API definition with TypeSpec. TypeSpec has an official HTTP API "binding" called `@typespec/http`. It's a set of TypeSpec declarations and decorators that describe HTTP APIs and can be used by code generators to generate OpenAPI descriptions, implementation code, and the like.
 Built on top of the http library there is the rest library `@typespec/rest` which provide some REST concept like resources.

docs/introduction/editor/vs.md

@@ -1,4 +1,6 @@
-# TypeSpec Visual Studio Extension
+---
+title: TypeSpec Visual Studio Extension
+---
 
 ## Installation
 

docs/introduction/editor/vscode.md

@@ -1,4 +1,6 @@
-# TypeSpec VSCode extension
+---
+title: TypeSpec VSCode extension
+---
 
 ## Installation
 

docs/introduction/reproducibility.md

@@ -1,4 +1,6 @@
-# Reproducibility
+---
+title: Reproducibility
+---
 
 A key point to service definition is the ability to reliably reproduce the exact same output over time. In cases like:
 

docs/release-notes/cadl-typespec-migration.md

@@ -1,4 +1,6 @@
-# Cadl to TypeSpec rename completed in March 2023 release
+---
+title: Cadl to TypeSpec rename completed in March 2023 release
+---
 
 As you may recall from our previous email to partners, we are renaming the product as it becomes more mature, stable and one step closer to release.
 

docs/standard-library/discriminated-types.md

@@ -1,4 +1,6 @@
-# Discriminated types
+---
+title: Discriminated types
+---
 
 TypeSpec can express unions and inheritance. However, when sending types over the wire many languages need a way to discriminate between the various union variants or models in an inheritance hierarchy.
 

docs/standard-library/http/content-types.md

@@ -1,4 +1,6 @@
-# Content types
+---
+title: Content types
+---
 
 ## Default behavior
 

docs/standard-library/http/encoding.md

@@ -1,4 +1,6 @@
-# Encoding of types
+---
+title: Encoding of types
+---
 
 This document describe how the http library interpret TypeSpec built-in types and how to configure
 

eng/pipelines/jobs/build-and-test.yml

@@ -27,6 +27,10 @@ steps:
   - script: node eng/scripts/check-for-changed-files.js
     displayName: Check Git Status For Changed Files
 
+  - script: node eng/scripts/check-docs.js
+    displayName: Check docs
+    condition: ne(variables['Agent.OS'], 'Windows_NT')
+
   - script: node common/scripts/install-run-rush.js cspell
     displayName: Spell check
     condition: ne(variables['Agent.OS'], 'Windows_NT')

eng/scripts/check-docs.js

@@ -0,0 +1,63 @@
+// @ts-check
+
+// cspell:ignore astro
+// This script check the docs are compatible for astro to simplify migration
+// It check each docs has
+//  - a `title:` frontmatter
+import { readFile, readdir } from "fs/promises";
+import { resolve } from "path";
+import { repoRoot } from "./helpers.js";
+
+const docsFolder = resolve(repoRoot, "docs");
+
+async function findMarkdownFiles(folder) {
+  const items = await readdir(folder, { withFileTypes: true });
+
+  return (
+    await Promise.all(
+      items.map(async (item) => {
+        if (item.isDirectory()) {
+          const files = await findMarkdownFiles(resolve(folder, item.name));
+          return files.map((x) => resolve(folder, x));
+        }
+
+        if (item.name.endsWith(".md")) {
+          return [resolve(folder, item.name)];
+        } else {
+          return [];
+        }
+      })
+    )
+  ).flat();
+}
+await main();
+
+async function main() {
+  const docs = await findMarkdownFiles(docsFolder);
+
+  const failure = [];
+  const regex = /^---.*title:.*---$/ms;
+  for (const doc of docs) {
+    const buffer = await readFile(doc, { encoding: "utf-8" });
+    const content = buffer.toString();
+    if (!regex.test(content)) {
+      failure.push(doc);
+    }
+  }
+
+  if (failure.length > 0) {
+    console.log("Files with missing title: frontmatter", failure);
+
+    console.log(
+      [
+        "Make sure to add front matter in the file with title, e.g.:",
+        "---",
+        "title: xyz",
+        "---",
+      ].join("\n")
+    );
+    process.exit(1);
+  } else {
+    console.log("Docs look good!");
+  }
+}