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

* [Docs Site] Refactor partials property validation and docs

* update partial examples

* update anchor in markdown component aside

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,
 	changelogsNextSchema,
 	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/identity/idp-integration/entra-id.mdx

@@ -120,7 +120,7 @@ The Microsoft Entra ID integration allows you to synchronize IdP groups and auto
 
 <Render
 	file="access/enable-scim-on-dashboard"
-	params={{ idp: "Entra ID", and: " and ", supportgroups: "Support groups"}}
+	params={{ idp: "Entra ID", supportgroups: "Support groups"}}
 />
 
 ### 2. Configure SCIM in Entra ID

src/content/docs/style-guide/components/markdown.mdx

@@ -2,6 +2,12 @@
 title: Markdown
 ---
 
+:::caution
+This component does not use Astro to render the Markdown, as a result it cannot use components, `~/assets/` images or code blocks.
+
+Where feasible, use [JSX](/style-guide/components/render/#properties-in-markdown-syntax) instead
+:::
+
 This component uses `marked` to turn the `text` prop into HTML. This is useful with, for example partial files that have variables you need to format.
 
 ```mdx live

src/content/docs/style-guide/components/render.mdx

@@ -2,90 +2,174 @@
 title: Render
 ---
 
-import { Steps } from "~/components";
+import { Code, Details, Type, MetaInfo } from "~/components";
 
 The `Render` component allows us to include a "partial", a reusable Markdown snippet, onto a page.
 
-It also accepts parameters that can be used as variables within the partial, so that even content
-which needs slight differences between usages can be turned into a partial.
+It also accepts parameters that can be used as variables within the partial, so that even content which needs slight differences between usages can be turned into a partial.
 
 ## Component
 
 ```mdx live
 import { Render } from "~/components";
 
-<Render file="hello" params={{
+<Render file="simple-props" params={{
     name: "world",
-    link: "/style-guide/components/render/"
 }} />
-{/*
-Hello, {props.name}!
+```
 
-Hello `{props.name}`
+### Inputs
 
-Hello <code>{props.name}</code>
+- `file` <Type text="string" />
 
-[link]({props.link})
+	This should be the name of the partial, without the containing directory or file extension. For example, `/partials/style-guide/hello.mdx` would be `file="hello"`.
 
-<a href={props.link}>link</a>
-*/}
-```
+- `product` <Type text="string" /> <MetaInfo text="optional" />
 
-### Inputs
+	By default, it will look for partials in the same product folder as the current page. You can use this to specify a different product.
+
+	:::caution
+
+	When using the `Render` component inside partials, the original `product` is lost.
+
+	For example, if there are three files:
+
+	1. `docs/fundamentals/index.mdx`
+	2. `partials/dns/thing.mdx`
+	3. `partials/dns/thing2.mdx`
 
-**file** `string`: This should be the name of the partial, without the containing directory or file extension.
-For example, `/partials/style-guide/hello.mdx` would be `file="hello"`.
+	`docs/fundamentals/index.mdx` uses `<Render file="thing" product="dns" />`
 
-**product** `string` (optional): By default, it will look for partials in the same product folder as the current page.
-You can use this to specify a different product.
+	`partials/dns/thing.mdx` must use `<Render file="thing2" product="dns" />` as `product` cannot be inferred.
 
-**params** `object` (optional): If you wish to substitute values inside your partial, you can use pass params which can be
-referenced in your partial. Refer to [params](#params).
+	:::
 
-## Partials
+- `params` <Type text="object" /> <MetaInfo text="optional" />
 
-Partials only have one optional frontmatter property, which is `params`. This takes an array of strings,
-which should be the expected parameters. When this is defined, but those parameters are not passed, an error
-will be thrown.
+	If you wish to substitute values inside your partial, you can use pass params which can be referenced in your partial. Refer to [properties](#properties).
 
-```mdx title="/src/content/partials/style-guide/hello.mdx"
+## Properties
+
+### Defining expected properties in frontmatter
+
+Anything defined in the `params` property of the `Render` component is available inside the partial, using [JavaScript expressions](https://mdxjs.com/docs/using-mdx/).
+
+To protect against required properties being missed, any partial that relies on `params` should also define `params` in the partial's frontmatter. This should be an array of strings, matching the property names you expect. If a property is optional, such as for [conditional content](#properties-to-render-content-conditionally), add a `?` to the end of the name.
+
+```mdx
 ---
 params:
-  - name
-  - foo
-  - bar
+  - product
+  - deprecated?
 ---
+```
+
+For each of the below examples, you can open the dropdown to view the partial's content.
+
+### Properties as a plain string
+
+The below example would render `Hello, world!`.
+
+import simpleRaw from "~/content/partials/style-guide/simple-props.mdx?raw";
+
+<Details header="simple-props.mdx">
+	<Code code={simpleRaw} lang="mdx" />
+</Details>
+
+```mdx live
+import { Render } from "~/components";
+
+<Render file="simple-props" params={{ name: "world" }} />
+```
+
+### Properties in Markdown syntax
+
+When using JavaScript expressions, you are now "inside JSX" and cannot use traditional Markdown syntax. Similarly, you cannot use a JavaScript expression inside Markdown syntax.
+
+Ideally, you should not use Markdown syntax, such as `**strong**` or `[text](link)`, with properties. If using JSX is not feasible, there is a [`Markdown`](/style-guide/components/markdown/) component that will take a `text` property.
+
+The [MDX documentation](https://mdxjs.com/table-of-components/#components) includes a mapping of common Markdown syntax to their equivalent JSX elements.
+
+#### Strong
+
+import strongRaw from "~/content/partials/style-guide/strong-in-props.mdx?raw";
 
-Hello, {props.name}!
+<Details header="strong-in-props.mdx">
+	<Code code={strongRaw} lang="mdx" />
+</Details>
 
-Hello, {props.foo}!
+```mdx live
+import { Render } from "~/components";
 
-Hello, {props.bar}!
+<Render file="strong-in-props" params={{ do: "Text", dont: "**Text**" }} />
 ```
 
-### Params
+#### Links
+
+import linkRaw from "~/content/partials/style-guide/link-in-props.mdx?raw";
+
+<Details header="link-in-props.mdx">
+	<Code code={linkRaw} lang="mdx" />
+</Details>
 
-In the above example, you will notice there is:
+```mdx live
+import { Render } from "~/components";
 
-<Steps>
+<Render file="link-in-props" params={{
+	link: "/style-guide/components/render/#links"
+}} />
+```
 
-1. A `params` input on the `Render` component.
-2. A `params` property in the frontmatter. 
-3. A reference to `props.name`.
+#### Images
+
+import imageRaw from "~/content/partials/style-guide/image-in-props.mdx?raw";
+
+<Details header="image-in-props.mdx">
+	<Code code={imageRaw} lang="mdx" />
+</Details>
+
+```mdx live
+import { Render } from "~/components";
+
+<Render file="image-in-props" params={{ image: "/logo.svg" }} />
+```
 
-</Steps>
+#### Code blocks
 
-#### Input
+import codeRaw from "~/content/partials/style-guide/code-in-props.mdx?raw";
+
+<Details header="code-in-props.mdx">
+	<Code code={codeRaw} lang="mdx" />
+</Details>
+
+```mdx live
+import { Render } from "~/components";
+
+<Render file="code-in-props" params={{ code: "export const foo = 'bar';" }} />
+```
+
+### Properties to render content conditionally
+
+Anything that you can represent in a JavaScript expression can be used in your conditional logic.
+
+This may be the [and (`&&`) operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND) or [ternary (`? ... : ... `) operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator), the below example uses both.
+
+import optionalRaw from "~/content/partials/style-guide/optional-props.mdx?raw";
+
+<Details header="optional-props.mdx">
+	<Code code={optionalRaw} lang="mdx" />
+</Details>
+
+```mdx live
+import { Render } from "~/components";
 
-When using the `params` input on the `Render` component, you can write a [JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_objects)
-which is later available inside the partial.
+<Render file="optional-props" params={{ product: "Thing", deprecated: true }} />
 
-#### Frontmatter
+<hr />
 
-The `params` frontmatter property on a partial expects an array of strings, containing the "expected parameters". This is so that if
-your partial requires parameters to be passed, and none are passed, we can warn the user.
+<Render file="optional-props" params={{ product: "Thing Two" }} />
 
-#### Props
+<hr />
 
-The way that you can access these parameters is with the `props` object, surrounded in curly braces `{}`.
-This is a [JavaScript expression within MDX](https://mdxjs.com/docs/using-mdx/#props).
+<Render file="optional-props" params={{ product: "Thing Three" }} />
+```

src/content/partials/cloudflare-one/access/enable-scim-on-dashboard.mdx

@@ -1,8 +1,7 @@
 ---
 params:
   - idp
-  - and
-  - supportgroups
+  - supportgroups?
 ---
 
 import { Markdown } from "~/components"
@@ -11,7 +10,7 @@ import { Markdown } from "~/components"
 
 2. Find the {props.idp} integration and select **Edit**.
 
-3. Turn on **Enable SCIM**{props.and}**{props.supportgroups}**.
+3. Turn on **Enable SCIM** {props.supportgroups && <span> and <strong>props.supportgroups</strong>.</span>}
 
 4. (Optional) Configure the following settings: