From 6bc4ef47eccfadbdafb4560a61ca0c82218d6074 Mon Sep 17 00:00:00 2001
From: Juri Strumpflohner <juri.strumpflohner@gmail.com>
Date: Fri, 13 Jun 2025 14:52:53 +0200
Subject: [PATCH] feat(nx-dev): read description from markdown frontmatter for
 index pages (#31566)

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior

Index pages read from the map.json description which is missing for a
lot of entries.

<img width="853" alt="image"
src="https://github.com/user-attachments/assets/8c0db9a2-d293-482d-8597-647cda47cc93"
/>


## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

The new logic

- checks the corresponding markdown file `description` property which is
also used for the HTML meta description tags
- falls back to the `map.json` description

<img width="809" alt="image"
src="https://github.com/user-attachments/assets/716358f0-bab9-4bd4-97b2-b31fa151ebe0"
/>



## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #
---
 .../src/lib/documents.api.ts                  | 38 ++++++++++++++++---
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/nx-dev/data-access-documents/src/lib/documents.api.ts b/nx-dev/data-access-documents/src/lib/documents.api.ts
index 578b1d43de..2aa890dacf 100644
--- a/nx-dev/data-access-documents/src/lib/documents.api.ts
+++ b/nx-dev/data-access-documents/src/lib/documents.api.ts
@@ -5,9 +5,10 @@ import {
   type RelatedDocument,
 } from '@nx/nx-dev/models-document';
 import { type ProcessedPackageMetadata } from '@nx/nx-dev/models-package';
-import { readdirSync, readFileSync } from 'node:fs';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { type TagsApi } from './tags.api';
+import { extractFrontmatter } from '@nx/nx-dev/ui-markdoc';
 
 interface StaticDocumentPaths {
   params: { segments: string[] };
@@ -282,11 +283,36 @@ export class DocumentsApi {
 
   generateDocumentIndexTemplate(document: DocumentMetadata): string {
     const cardsTemplate = document.itemList
-      .map((i) => ({
-        title: i.name,
-        description: i.description ?? '',
-        url: i.path,
-      }))
+      .map((i) => {
+        // Try to get description from frontmatter first
+        let description = i.description ?? '';
+
+        // Get the document metadata to find the file path
+        // i.path might already have a leading slash or might not, so we need to check both
+        const itemDocument =
+          this.manifest[i.path] || this.manifest[this.getManifestKey(i.path)];
+
+        if (itemDocument && itemDocument.file) {
+          const filePath = this.getFilePath(`${itemDocument.file}.md`);
+          if (existsSync(filePath)) {
+            try {
+              const content = readFileSync(filePath, 'utf8');
+              const frontmatter = extractFrontmatter(content);
+              // Use frontmatter description if available, otherwise fall back to map.json description
+              description = frontmatter.description || description;
+            } catch (e) {
+              // If there's an error reading the file, fall back to the original description
+              console.warn(`Could not read frontmatter from ${filePath}:`, e);
+            }
+          }
+        }
+
+        return {
+          title: i.name,
+          description,
+          url: i.path,
+        };
+      })
       .map(
         (card) =>
           `{% card title="${card.title}" description="${