feat: Include API summary in <meta description> tag (#9611)

Author: yufeih

src/Docfx.Build/ApiPage/ApiPageProcessor.cs

@@ -41,13 +41,18 @@ public FileModel Load(FileAndType file, ImmutableDictionary<string, object> meta
         var yml = EnvironmentContext.FileAbstractLayer.ReadAllText(file.File);
         var json = JsonSerializer.Serialize(deserializer.Deserialize<object>(yml));
         var data = JsonSerializer.Deserialize<ApiPage>(json, ApiPage.JsonSerializerOptions);
-        var content = new Dictionary<string, object>(metadata.OrderBy(item => item.Key))
+        var content = new Dictionary<string, object>(metadata.OrderBy(item => item.Key));
+
+        if (data.metadata is not null)
         {
-            ["title"] = data.title,
-            ["content"] = ApiPageHtmlTemplate.Render(data, Markup).ToString(),
-            ["yamlmime"] = "ApiPage",
-            ["_disableNextArticle"] = true,
-        };
+            foreach (var (key, value) in data.metadata.OrderBy(item => item.Key))
+                content[key] = value.Value;
+        }
+        
+        content["title"] = data.title;
+        content["content"] = ApiPageHtmlTemplate.Render(data, Markup).ToString();
+        content["yamlmime"] = "ApiPage";
+        content["_disableNextArticle"] = true;
 
         var localPathFromRoot = PathUtility.MakeRelativePath(EnvironmentContext.BaseDirectory, EnvironmentContext.FileAbstractLayer.GetPhysicalPath(file.File));
 

src/Docfx.Dotnet/Docfx.Dotnet.csproj

@@ -29,6 +29,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="HtmlAgilityPack" />
     <PackageReference Include="ICSharpCode.Decompiler" />
     <PackageReference Include="IgnoresAccessChecksToGenerator" PrivateAssets="All" />
     <PackageReference Include="OneOf" />

src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs

@@ -10,6 +10,7 @@
 using Docfx.Common.Git;
 using Docfx.DataContracts.ManagedReference;
 using Docfx.Plugins;
+using HtmlAgilityPack;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.Shared.Extensions;
 using OneOf;
@@ -96,9 +97,14 @@ _ when SymbolHelper.IsMember(method) => "Method",
                     throw new NotSupportedException($"Unknown symbol type kind {symbols[0].symbol}");
             }
 
+            var metadata = new Dictionary<string, OneOf<string, string[]>>();
+            if (!string.IsNullOrEmpty(comment?.Summary))
+                metadata["description"] = HtmlInnerText(comment.Summary);
+
             output(config.OutputFolder, id, new ApiPage
             {
                 title = title,
+                metadata = metadata.Count > 0 ? metadata : null,
                 languageId = "csharp",
                 body = body.ToArray(),
             });
@@ -760,6 +766,13 @@ Span Link(string text, string? url)
             });
         }
     }
+
+    static string HtmlInnerText(string html)
+    {
+        var doc = new HtmlDocument();
+        doc.LoadHtml(html);
+        return doc.DocumentNode.InnerText;
+    }
 }
 
 #endif

templates/common/ManagedReference.common.js

@@ -36,6 +36,10 @@ exports.transform = function (model) {
     }
   }
 
+  if (model.summary && !model.description) {
+    model.description = model.summary.replace(/<.*?>/gi, '').replace(/(\r\n|\n|\r)/gm, ' ').trim();
+  }
+
   return model;
 }
 

test/docfx.Snapshot.Tests/SamplesTest.CSharp.Linux/api/CSharp8.Issue4007.html.view.verified.json

@@ -1006,6 +1006,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This works: . This does not work: .",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.CSharp.Windows/api/CSharp8.Issue4007.html.view.verified.json

@@ -1006,6 +1006,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This works: . This does not work: .",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/BuildFromAssembly.Class1.html.view.verified.json

@@ -847,6 +847,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This is a test class.",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/BuildFromProject.Inheritdoc.Issue7484.html.view.verified.json

@@ -1144,6 +1144,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This is a test class to have something for DocFX to document.",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/BuildFromProject.Issue8725.html.view.verified.json

@@ -904,6 +904,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "A nice class",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/BuildFromVBSourceCode.BaseClass1.html.view.verified.json

@@ -911,6 +911,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This is the BaseClass",
   "_disableToc": false,
   "_disableNextArticle": true
 }