[Docs Site] Refactor partials property validation and docs (#19887)

* [Docs Site] Refactor partials property validation and docs

* update partial examples

* fix partials that would fail validation

* fix partial

Author: KianNH

astro.config.ts

@@ -8,14 +8,15 @@ import starlightLinksValidator from "starlight-links-validator";
 import icon from "astro-icon";
 import sitemap from "@astrojs/sitemap";
 import react from "@astrojs/react";
+
 import { readdir } from "fs/promises";
+import { fileURLToPath } from "url";
 
 import rehypeTitleFigure from "rehype-title-figure";
 import rehypeMermaid from "./src/plugins/rehype/mermaid.ts";
 import rehypeAutolinkHeadings from "./src/plugins/rehype/autolink-headings.ts";
 import rehypeExternalLinks from "./src/plugins/rehype/external-links.ts";
 import rehypeHeadingSlugs from "./src/plugins/rehype/heading-slugs.ts";
-import { fileURLToPath } from "url";
 
 async function autogenSections() {
 	const sections = (

src/components/Render.astro

@@ -13,29 +13,49 @@ const props = z.object({
 let { file, product, params } = props.parse(Astro.props);
 
 if (!product) {
-	product = Astro.params.slug?.split("/")[0];
-}
+	const fromSlug = Astro.params.slug?.split("/")[0];
 
-if (!product) {
-	throw new Error(
-		`[Render] Unable to infer which folder ${file} is in, please provide a "product" input with your "file" input.`,
-	);
+	if (!fromSlug) {
+		throw new Error(
+			`[Render] Unable to infer which folder ${file} is in, please provide a "product" input with your "file" input.`,
+		);
+	}
+
+	product = fromSlug;
 }
 
-const partial = await getEntry("partials", `${product}/${file}`);
+const id = `${product}/${file}`;
+const partial = await getEntry("partials", id);
 
 if (!partial) {
 	throw new Error(
-		`[Render] Couldn't find partial: ${file}. Included on ${Astro.params.slug}`,
+		`[Render] Couldn't find "${id}" included on "${Astro.url.pathname}"`,
 	);
 }
 
+// We currently only enforce parameters if `params` is set in the frontmatter,
+// until we can migrate existing `inputParameters` frontmatter to `params`.
 if (partial.data.params) {
-	const expected = partial.data.params;
-	if (!params)
+	const expected = partial.data.params.sort();
+	const optional = expected.filter((p) => p.endsWith("?"));
+	const received = Object.keys(params ?? {}).sort();
+
+	const maximum = expected.length;
+	const minimum = maximum - optional.length;
+
+	if (
+		received.length < minimum ||
+		received.length > maximum ||
+		expected.some((p: string) => {
+			if (p.endsWith("?")) return false;
+
+			return !received.includes(p);
+		})
+	) {
 		throw new Error(
-			`${file} included on ${Astro.params.slug} expected parameters: ${expected}, got none`,
+			`[Render] Expected parameters ${JSON.stringify(expected)} but received parameters ${JSON.stringify(received)} for "${file}" included on "${Astro.url.pathname}"`,
 		);
+	}
 }
 
 const { Content } = await render(partial);

src/content.config.ts

@@ -1,4 +1,4 @@
-import { z, defineCollection } from "astro:content";
+import { defineCollection } from "astro:content";
 
 import { docsLoader, i18nLoader } from "@astrojs/starlight/loaders";
 import { docsSchema, i18nSchema } from "@astrojs/starlight/schema";
@@ -20,6 +20,7 @@ import {
 	warpReleasesSchema,
 	releaseNotesSchema,
 	fieldsSchema,
+	partialsSchema,
 } from "~/schemas";
 
 function contentLoader(name: string) {
@@ -36,10 +37,6 @@ function dataLoader(name: string) {
 	});
 }
 
-const partialSchema = z.object({
-	params: z.string().array().optional(),
-});
-
 export const collections = {
 	docs: defineCollection({
 		loader: docsLoader(),
@@ -61,7 +58,7 @@ export const collections = {
 	}),
 	partials: defineCollection({
 		loader: contentLoader("partials"),
-		schema: partialSchema,
+		schema: partialsSchema,
 	}),
 	glossary: defineCollection({
 		loader: dataLoader("glossary"),

src/content/docs/cloudflare-one/applications/casb/casb-integrations/atlassian-confluence.mdx

@@ -9,8 +9,8 @@ import { Render } from "~/components";
 <Render
   file="casb/integration-description"
   params={{
-    one: "Atlassian Confluence",
-    two: "Atlassian Confluence Cloud account",
+    integrationName: "Atlassian Confluence",
+    integrationAccountType: "Atlassian Confluence Cloud account",
   }}
 />
 
@@ -43,7 +43,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 <Render
   file="casb/security-findings"
-  params={{ one: "Atlassian Confluence", two: "atlassian-confluence" }}
+  params={{ integrationName: "Atlassian Confluence", slugRelativePath: "atlassian-confluence" }}
 />
 
 ### Access security

src/content/docs/cloudflare-one/applications/casb/casb-integrations/atlassian-jira.mdx

@@ -8,7 +8,7 @@ import { Render } from "~/components";
 
 <Render
   file="casb/integration-description"
-  params={{ one: "Atlassian Jira", two: "Atlassian Jira Cloud account" }}
+  params={{ integrationName: "Atlassian Jira", integrationAccountType: "Atlassian Jira Cloud account" }}
 />
 
 :::note
@@ -35,7 +35,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 <Render
   file="casb/security-findings"
-  params={{ one: "Jira Cloud", two: "atlassian-jira" }}
+  params={{ integrationName: "Jira Cloud", slugRelativePath: "atlassian-jira" }}
 />
 
 ### Access security

src/content/docs/cloudflare-one/applications/casb/casb-integrations/aws-s3.mdx

@@ -8,7 +8,7 @@ import { Render } from "~/components";
 
 <Render
 	file="casb/integration-description"
-	params={{ one: "Amazon Web Services (AWS) S3", two: "AWS account" }}
+	params={{ integrationName: "Amazon Web Services (AWS) S3", integrationAccountType: "AWS account" }}
 />
 
 ## Integration prerequisites
@@ -65,7 +65,7 @@ For more information, refer to [Content findings](/cloudflare-one/applications/c
 
 <Render
 	file="casb/security-findings"
-	params={{ one: "AWS S3", two: "aws-s3" }}
+	params={{ integrationName: "AWS S3", slugRelativePath: "aws-s3" }}
 />
 
 ### S3 Bucket security

src/content/docs/cloudflare-one/applications/casb/casb-integrations/bitbucket-cloud.mdx

@@ -8,7 +8,7 @@ import { Render } from "~/components";
 
 <Render
   file="casb/integration-description"
-  params={{ one: "Bitbucket Cloud", two: "Bitbucket Cloud Cloud account" }}
+  params={{ integrationName: "Bitbucket Cloud", integrationAccountType: "Bitbucket Cloud Cloud account" }}
 />
 
 :::note
@@ -46,7 +46,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 <Render
   file="casb/security-findings"
-  params={{ one: "Bitbucket Cloud", two: "bitbucket-cloud" }}
+  params={{ integrationName: "Bitbucket Cloud", slugRelativePath: "bitbucket-cloud" }}
 />
 
 ### Repository security

src/content/docs/cloudflare-one/applications/casb/casb-integrations/box.mdx

@@ -8,7 +8,7 @@ import { Render } from "~/components";
 
 <Render
   file="casb/integration-description"
-  params={{ one: "Box", two: "Box account" }}
+  params={{ integrationName: "Box", integrationAccountType: "Box account" }}
 />
 
 ## Integration prerequisites
@@ -27,7 +27,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 ## Security findings
 
-<Render file="casb/security-findings" params={{ one: "Box", two: "box" }} />
+<Render file="casb/security-findings" params={{ integrationName: "Box", slugRelativePath: "box" }} />
 
 ### File sharing
 

src/content/docs/cloudflare-one/applications/casb/casb-integrations/dropbox.mdx

@@ -8,7 +8,7 @@ import { Render } from "~/components";
 
 <Render
   file="casb/integration-description"
-  params={{ one: "Dropbox", two: "Dropbox account" }}
+  params={{ integrationName: "Dropbox", integrationAccountType: "Dropbox account" }}
 />
 
 ## Integration prerequisites
@@ -39,7 +39,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 <Render
   file="casb/security-findings"
-  params={{ one: "Dropbox", two: "dropbox" }}
+  params={{ integrationName: "Dropbox", slugRelativePath: "dropbox" }}
 />
 
 ### File and folder sharing

src/content/docs/cloudflare-one/applications/casb/casb-integrations/github.mdx

@@ -11,7 +11,7 @@ import { Render } from "~/components";
 
 <Render
   file="casb/integration-description"
-  params={{ one: "GitHub", two: "GitHub Organization" }}
+  params={{ integrationName: "GitHub", integrationAccountType: "GitHub Organization" }}
 />
 
 ## Integration prerequisites
@@ -36,7 +36,7 @@ These permissions follow the principle of least privilege to ensure that only th
 
 <Render
   file="casb/security-findings"
-  params={{ one: "GitHub", two: "github" }}
+  params={{ integrationName: "GitHub", slugRelativePath: "github" }}
 />
 
 ### Branches and merges