chore(core): add map.json jsonschema (#12701)

docs/map.json

@@ -1,4 +1,8 @@
-[
+{
+  "$schema": "./../scripts/documentation/map-schema.json",
+  "title": "Documentation map reference",
+  "description": "This is used to create documentation routing and hierarchy on the nx.dev website.",
+  "content": [
     {
       "name": "Nx docs",
       "id": "nx-documentation",
@@ -1184,7 +1188,11 @@
               "id": "run",
               "file": "generated/cli/run"
             },
-          { "name": "daemon", "id": "daemon", "file": "generated/cli/daemon" },
+            {
+              "name": "daemon",
+              "id": "daemon",
+              "file": "generated/cli/daemon"
+            },
             {
               "name": "graph",
               "id": "dep-graph",
@@ -1241,7 +1249,11 @@
               "tags": ["automate-updating-dependencies"],
               "file": "generated/cli/migrate"
             },
-          { "name": "report", "id": "report", "file": "generated/cli/report" },
+            {
+              "name": "report",
+              "id": "report",
+              "file": "generated/cli/report"
+            },
             { "name": "list", "id": "list", "file": "generated/cli/list" },
             {
               "name": "workspace-lint",
@@ -1613,3 +1625,4 @@
       ]
     }
   ]
+}

nx-dev/nx-dev/lib/api.ts

@@ -24,10 +24,10 @@ export const packagesApi = new PackagesApi({
 export const nxDocumentsApi = new DocumentsApi({
   publicDocsRoot: 'nx-dev/nx-dev/public/documentation',
   documentSources: [
-    documents.find(
+    documents.content.find(
       (x) => x.id === 'nx-documentation'
     ) as Partial<DocumentMetadata>,
-    documents.find(
+    documents.content.find(
       (x) => x.id === 'additional-api-references'
     ) as Partial<DocumentMetadata>,
   ]
@@ -37,15 +37,15 @@ export const nxDocumentsApi = new DocumentsApi({
 });
 export const nxRecipesApi = new DocumentsApi({
   publicDocsRoot: 'nx-dev/nx-dev/public/documentation',
-  documentSources: [documents.find((x) => x.id === 'nx-recipes')].filter(
+  documentSources: [
-    (x) => !!x
+    documents.content.find((x) => x.id === 'nx-recipes'),
-  ) as DocumentMetadata[],
+  ].filter((x) => !!x) as DocumentMetadata[],
   addAncestor: { id: 'recipes', name: 'Recipes' },
 });
 export const nxCloudDocumentsApi = new DocumentsApi({
   publicDocsRoot: 'nx-dev/nx-dev/public/documentation',
   documentSources: [
-    documents.find(
+    documents.content.find(
       (x) => x.id === 'nx-cloud-documentation'
     ) as Partial<DocumentMetadata>,
   ]

scripts/documentation/map-link-checker.ts

@@ -37,7 +37,7 @@ function filePathExtractor(file: any): string[] {
 const mapPathList: string[] = readJsonSync(`${basePath}/map.json`, {
   encoding: 'utf8',
 })
-  .map((file: any) => filePathExtractor(file))
+  .content.map((file: any) => filePathExtractor(file))
   .flat();
 const readmeMissList = readmePathList.filter((x) => !mapPathList.includes(x));
 const mapMissList = mapPathList.filter((x) => !readmePathList.includes(x));

scripts/documentation/map-schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "documentation-map-schema",
+  "title": "JSON schema for documentation map",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Title of the document"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the document"
+    },
+    "content": {
+      "type": "array",
+      "description": "Dictionary map section",
+      "items": {
+        "$ref": "#/definitions/entry"
+      }
+    }
+  },
+  "definitions": {
+    "entry": {
+      "type": "object",
+      "required": ["name", "id"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Name for the current item"
+        },
+        "id": {
+          "type": "string",
+          "description": "Identifier for the current item"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description for the item"
+        },
+        "file": {
+          "type": "string",
+          "description": "Path to the markdown file"
+        },
+        "tags": {
+          "type": "array",
+          "description": "Tags are used on nx.dev to link related piece of content together (e.g: Related Documentation)"
+        },
+        "path": {
+          "type": "string",
+          "description": "Custom path or URL to find the item on nx.dev"
+        },
+        "isExternal": {
+          "type": "boolean",
+          "description": "Is the path provided is external to nx.dev?"
+        },
+        "itemList": {
+          "type": "array",
+          "description": "Children for the item",
+          "items": {
+            "$ref": "#/definitions/entry"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

scripts/documentation/open-graph/generate-images.ts

@@ -2,7 +2,7 @@ import { Canvas, Image, SKRSContext2D } from '@napi-rs/canvas';
 import { ensureDir, readFile, readJSONSync, writeFileSync } from 'fs-extra';
 import { resolve } from 'path';
 
-const mapJson = readJSONSync('./docs/map.json', 'utf8');
+const mapJson = readJSONSync('./docs/map.json', 'utf8').content;
 
 const documents: any[] = [
   ...mapJson.find((x) => x.id === 'nx-documentation')?.['itemList'],

scripts/documentation/package-schemas/package-metadata.ts

@@ -85,7 +85,7 @@ export function getPackageMetadataList(
   /**
    * Get all the custom overview information on each package if available
    */
-  const additionalApiReferences: any = DocumentationMap.find(
+  const additionalApiReferences: any = DocumentationMap.content.find(
     (data) => data.id === 'additional-api-references'
   ).itemList;