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

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
 }

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

@@ -1513,6 +1513,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "This is summary from vb class...",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.Cat-2.html.view.verified.json

@@ -4296,6 +4296,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "Here's main class of this Demo. You can see mostly type of article within this class and you for more detail, please see the remarks.  this class is a template class. It has two Generic parameter. they are: T and K. The extension method of this class can refer to  class",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.Core.ContainersRefType.ColorType.html.view.verified.json

@@ -597,6 +597,7 @@
   "hideSubtitle": false,
   "isClass": false,
   "inEnum": true,
+  "description": "Enumeration ColorType",
   "isEnum": true,
   "_disableToc": false,
   "_disableNextArticle": true

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.Core.ContainersRefType.ContainersRefTypeDelegate.html.view.verified.json

@@ -187,6 +187,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inDelegate": true,
+  "description": "Delegate ContainersRefTypeDelegate",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.Core.ContainersRefType.html.view.verified.json

@@ -1284,6 +1284,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inStruct": true,
+  "description": "Struct ContainersRefType",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.FakeDelegate-1.html.view.verified.json

@@ -382,6 +382,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inDelegate": true,
+  "description": "Fake delegate",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.IAnimal.html.view.verified.json

@@ -1120,6 +1120,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inInterface": true,
+  "description": "This is basic interface of all animal.",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.ICat.html.view.verified.json

@@ -686,6 +686,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inInterface": true,
+  "description": "Cat's interface",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.ICatExtension.html.view.verified.json

@@ -1048,6 +1048,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "It's the class that contains ICat interface's extension method. This class must be public and static. Also it shouldn't be a geneic class",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.MRefDelegate-3.html.view.verified.json

@@ -347,6 +347,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inDelegate": true,
+  "description": "Generic delegate with many constrains.",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.MRefNormalDelegate.html.view.verified.json

@@ -284,6 +284,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inDelegate": true,
+  "description": "Delegate in the namespace",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.Tom.html.view.verified.json

@@ -1027,6 +1027,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "Tom class is only inherit from Object. Not any member inside itself.",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/CatLibrary.TomFromBaseClass.html.view.verified.json

@@ -874,6 +874,7 @@
   "hideSubtitle": false,
   "isClass": true,
   "inClass": true,
+  "description": "TomFromBaseClass inherits from @",
   "_disableToc": false,
   "_disableNextArticle": true
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Linux/api/MRef.Demo.Enumeration.ColorType.html.view.verified.json

@@ -645,6 +645,7 @@
   "hideSubtitle": false,
   "isClass": false,
   "inEnum": true,
+  "description": "Enumeration ColorType",
   "isEnum": true,
   "_disableToc": false,
   "_disableNextArticle": true