[Docs Site] Add maxDepth to DirectoryListing (#21411)

Author: KianNH

src/components/DirectoryListing.astro

@@ -2,46 +2,60 @@
 import { z } from "astro:schema";
 import { getCollection } from "astro:content";
 import { sortBySidebarOrder } from "~/util/sidebar";
-import { marked } from "marked";
+import DirectoryListingItem from "./DirectoryListingItem.astro";
+
+interface PageNode {
+	page: (typeof allPages)[0];
+	children: PageNode[];
+}
 
 type Props = z.infer<typeof props>;
 
 const props = z.object({
 	descriptions: z.boolean().default(false),
 	folder: z.string().optional(),
+	maxDepth: z.number().default(1),
 });
 
-let { descriptions, folder } = props.parse(Astro.props);
+let { descriptions, folder, maxDepth } = props.parse(Astro.props);
 
 if (!folder) folder = Astro.params.slug!;
 
-const depth = folder.split("/").length + 1;
+const baseDepth = folder.split("/").length;
 
-let pages = await getCollection("docs", (page) => {
-	return (
-		page.id.startsWith(`${folder}/`) && page.id.split("/").length === depth
-	);
+let allPages = await getCollection("docs", (page) => {
+	const pageDepth = page.id.split("/").length;
+	return page.id.startsWith(`${folder}/`) && pageDepth <= baseDepth + maxDepth;
 });
 
-pages.sort(sortBySidebarOrder);
+allPages.sort(sortBySidebarOrder);
+
+function getChildren(parentPath: string, depth: number) {
+	return allPages.filter((page) => {
+		const pagePath = page.id;
+		const pageDepth = pagePath.split("/").length;
+		return pageDepth === depth && pagePath.startsWith(parentPath);
+	});
+}
+
+function buildPageTree(parentPath: string, currentDepth: number): PageNode[] {
+	const children = getChildren(parentPath, currentDepth);
+	return children.map((page) => ({
+		page,
+		children:
+			currentDepth < baseDepth + maxDepth
+				? buildPageTree(page.id, currentDepth + 1)
+				: [],
+	}));
+}
+
+const pageTree = buildPageTree(folder, baseDepth + 1);
 ---
 
 <ul>
 	{
-		pages.map((page) => {
-			const description = descriptions && page.data.description;
-			const href = page.data.external_link ?? "/" + page.id + "/";
-			return (
-				<li>
-					<a href={href}>{page.data.title}</a>
-					{description && (
-						<>
-							<span>: </span>
-							<Fragment set:html={marked.parseInline(description)} />
-						</>
-					)}
-				</li>
-			);
-		})
+		pageTree.map((node) => (
+			<DirectoryListingItem node={node} descriptions={descriptions} />
+		))
 	}
 </ul>

src/components/DirectoryListingItem.astro

@@ -0,0 +1,37 @@
+---
+import { marked } from "marked";
+import type { CollectionEntry } from "astro:content";
+
+interface Props {
+	node: {
+		page: CollectionEntry<"docs">;
+		children: Array<Props["node"]>;
+	};
+	descriptions: boolean;
+}
+
+const { node, descriptions } = Astro.props;
+---
+
+<li>
+	<a href={node.page.data.external_link ?? "/" + node.page.id + "/"}>
+		{node.page.data.title}
+	</a>
+	{
+		descriptions && node.page.data.description && (
+			<>
+				<span>: </span>
+				<Fragment set:html={marked.parseInline(node.page.data.description)} />
+			</>
+		)
+	}
+	{
+		node.children.length > 0 && (
+			<ul>
+				{node.children.map((child) => (
+					<Astro.self node={child} descriptions={descriptions} />
+				))}
+			</ul>
+		)
+	}
+</li>

src/content/docs/style-guide/components/directory-listing.mdx

@@ -8,14 +8,51 @@ import { Render } from "~/components";
 
 <Render file="directory-listing-definition" />
 
-We also have an optional `descriptions` parameter which - if present - adds in the text from the [front matter `description`](/style-guide/frontmatter/) field.
+## Usage
 
 ```mdx live
 import { DirectoryListing } from "~/components";
 
+<p>
+	<strong>Default</strong>
+</p>
+<DirectoryListing folder="workers/wrangler" />
+
+<br />
+
+<p>
+	<strong>maxDepth</strong>
+</p>
+<DirectoryListing folder="workers/wrangler" maxDepth={2} />
+
+<p>
+	<strong>Descriptions</strong>
+</p>
 <DirectoryListing folder="workers/wrangler" descriptions />
 ```
 
+## Props
+
+### `folder`
+
+**type:** `string`
+
+The folder path to list contents from. If not provided, defaults to the current page's path.
+
+### `descriptions`
+
+**type:** `boolean`
+**default:** `false`
+
+When enabled, shows the [frontmatter `description`](/style-guide/frontmatter/) field for each page in the listing.
+
+### `maxDepth`
+
+**type:** `number`
+**default:** `1`
+
+Controls how many levels of nested pages to display. A value of `1` shows only direct children, while higher values will show deeper nesting levels.
+
 ## Associated content types
 
-- [Navigation](/style-guide/documentation-content-strategy/content-types/navigation/)
+- [Navigation](/style-guide/documentation-content-strategy/content-types/navigation/)