feat: Add feature to reset markdig extension settings that are added by default

.github/workflows/nightly.yml

@@ -0,0 +1,30 @@
+name: nightly
+on:
+  schedule:
+  - cron: '0 0 * * *'
+
+jobs:
+  publish-github-packages:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - id: version
+      uses: paulhatch/[email protected]
+      with:
+        version_format: ${major}.${minor}.${patch}-preview.${increment}
+
+    - uses: ./.github/actions/build
+
+    - name: dotnet pack
+      run: dotnet pack -c Release /p:Version=${{ steps.version.outputs.version }} -o drop/nuget
+
+    - name: dotnet nuget push
+      run: |
+        dotnet nuget push drop/nuget/*.nupkg --api-key "${{ secrets.GITHUB_TOKEN }}" --skip-duplicate --source https://nuget.pkg.github.com/dotnet/index.json
+

Directory.Packages.props

@@ -8,8 +8,8 @@
     <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
     <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
     <PackageVersion Include="Jint" Version="3.0.1" />
-    <PackageVersion Include="JsonSchema.Net" Version="6.0.4" />
-    <PackageVersion Include="Markdig" Version="0.35.0" />
+    <PackageVersion Include="JsonSchema.Net" Version="6.0.7" />
+    <PackageVersion Include="Markdig" Version="0.36.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.9.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.9.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.9.2" />
@@ -23,7 +23,7 @@
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="OneOf" Version="3.0.263" />
     <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.263" />
-    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240307-ac027" />
+    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240324-e7896" />
     <PackageVersion Include="PlantUml.Net" Version="1.4.80" />
     <PackageVersion Include="Spectre.Console" Version="0.48.0" />
     <PackageVersion Include="Spectre.Console.Cli" Version="0.48.0" />
@@ -37,7 +37,7 @@
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
     <PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
     <PackageVersion Include="Verify.DiffPlex" Version="2.3.0" />
-    <PackageVersion Include="Verify.Xunit" Version="23.3.0" />
+    <PackageVersion Include="Verify.Xunit" Version="23.5.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7" />
     <PackageVersion Include="xunit" Version="2.7.0" />
   </ItemGroup>

README.md

@@ -36,6 +36,9 @@ Docfx is planned to continue as a community-driven project. We hope to produce f
 
 For more information, refer to [Getting Started](http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html).
 
+> [!TIP]
+> Docfx publishes nightly builds to [GitHub Packages](https://github.com/orgs/dotnet/packages), this allows you to stay up-to-date with the latest developments in Docfx.
+
 ## Contributing
 
 Use [Discussions](https://github.com/dotnet/docfx/discussions) for questions and general discussions. 

docs/docs/markdown.md

@@ -50,6 +50,8 @@ Alternatively, set the `build.markdownEngineProperties.markdigExtensions` proper
 }
 ```
 
+The known extension names are listed in [MardownExtensions.Configure](https://github.com/xoofx/markdig/blob/master/src/Markdig/MarkdownExtensions.cs) method in the MarkDig project.
+
 > [!Note]
 > The custom configuration of extensions via the `build.markdownEngineProperties.markdigExtensions` property is not supported.
 

docs/reference/docfx-cli-reference/docfx-template.md

@@ -1,4 +1,4 @@
-# docfx build
+# docfx template
 
 ## Name
 

docs/reference/docfx-json-reference.md

@@ -10,9 +10,9 @@ The `docfx.json` file indicates that the directory is the root of a docfx projec
 }
 ```
 
-## Global properties 
+## Global properties
 
-### `rules`
+## `rules`
 
 Overrides default log message severity level. Key is the log code, supported values are `verbose`, `info`, `suggestion`, `warning`, `error`:
 
@@ -148,6 +148,7 @@ Templates are used to transform YAML files generated by `docfx` to human-readabl
   }
 }
 ```
+
 ```json
 {
   "build": {
@@ -166,7 +167,6 @@ The themes applied to the documentation. Theme is used to customize the styles g
 
 Theme is to provide general styles for all the generated pages. Files inside a theme will be generally copied to the output folder. A typical usage is, after YAML files are transformed to HTML pages, well-designed CSS style files in a Theme can then overwrite the default styles defined in template, e.g. `main.css`.
 
-
 ### `xref`
 
 Specifies the urls of xrefmap used by content files. Currently, it supports following scheme: http, https, file.
@@ -199,6 +199,45 @@ Sets the max parallelism. Setting 0 (default) is the same as setting to the coun
 
 Sets the parameters for the markdown engine, value is a JSON object.
 
+For example. It can enable additional markdig extensions with following settings.
+
+```json
+{
+  "build": {
+    "markdownEngineProperties": {
+      "markdigExtensions": [
+        "advanced"
+      ]
+    }
+  }
+}
+```
+
+List of available built-in markdig extensions are available at [this URL](https://github.com/xoofx/markdig/blob/fcb56fb03701cc1a07a52769908579adb8927ee2/src/Markdig/MarkdownExtensions.cs#L537-L650).
+
+It can't remove existing markdig extensions added by docfx.
+But It can reset settings to markdig default when specifing following extension names.
+
+- `AutoIdentifiers`
+- `EmphasisExtras`
+- `Emojis`
+
+### `customLinkResolver`
+
+Set the name of the `ICustomHrefGenerator` derived class.
+
+### `groups`
+
+Specifies the output folder of specified group name.
+
+```json
+"groups": {
+  "v1": {
+    "dest": "output_dir_v1"
+  }
+}
+```
+
 ### `sitemap`
 
 Specifies the options for generating [sitemap.xml](https://www.sitemaps.org/protocol.html) file:
@@ -320,6 +359,12 @@ Specifies the output folder of the generated metadata files relative to `docfx.j
 
 If set to true, DocFX would not render triple-slash-comments in source code as markdown.
 
+### `references`
+
+Specify additinal assembly reference files.
+This settings is used when generating metadata from DLLs or source files.
+Solution or project file-based metadata generation does not use this property.
+
 ### `filter`
 
 Specifies the filter configuration file, please go to [How to filter out unwanted apis attributes](../tutorial/howto_filter_out_unwanted_apis_attributes.md) for more details.
@@ -332,6 +377,10 @@ Disables the default filter configuration file.
 
 Disables generation of view source links.
 
+### `codeSourceBasePath`
+
+Specify the base directory that is used to resolve code source (e.g. `<code source="Example.cs">`).
+
 ### `properties`
 
 Specifies an optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to msbuild via the `/property:name=value` command line argument.
@@ -347,6 +396,7 @@ Specifies an optional set of MSBuild properties used when interpreting project f
   ]
 }
 ```
+
 > [!Note]
 > Make sure to specify `"TargetFramework": <one of the frameworks>` in your docfx.json when the project is targeting for multiple platforms.
 
@@ -372,7 +422,7 @@ Specifies how member pages are organized:
 
 When enabled, continues documentation generation in case of compilation errors.
 
-### `EnumSortOrder`
+### `enumSortOrder`
 
 Specifies how enum members are sorted:
 

src/Docfx.App/Config/BuildJsonConfig.cs

@@ -202,14 +202,13 @@ internal class BuildJsonConfig
     public string CustomLinkResolver { get; set; }
 
     /// <summary>
-    /// Define groups.
+    /// Specifies the output folder of specified group name.
     /// </summary>
     /// <example>
     /// <code>
     /// groups:{
     ///   "v1": {
-    ///     "dest": "v1",
-    ///     "extraMetadata01": {}
+    ///     "dest": "output_dir_v1"
     ///   }
     /// }
     /// </code>

src/Docfx.App/PdfBuilder.cs

@@ -291,7 +291,7 @@ await Parallel.ForEachAsync(pages, async (item, _) =>
             if (outline.pdfTocPage)
             {
                 var href = $"/_pdftoc{outlineUrl.AbsolutePath}";
-                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground  });
+                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground });
             }
 
             if (!string.IsNullOrEmpty(outline.href))
@@ -325,6 +325,9 @@ async Task MergePdf()
                     // Refresh TOC page numbers
                     updatePageNumbers(pageNumbers);
                     bytes = await printPdf(outline, url);
+
+                    if (bytes == null)
+                        continue;
                 }
 
                 using var document = PdfDocument.Open(bytes);

src/Docfx.Build.SchemaDriven/Validators/SchemaValidator.cs

@@ -11,6 +11,12 @@ public class SchemaValidator
 {
     private readonly JsonSchema _schema;
 
+    private static readonly EvaluationOptions DefaultOptions = new EvaluationOptions
+    {
+        ValidateAgainstMetaSchema = false,
+        OutputFormat = OutputFormat.List,
+    };
+
     static SchemaValidator()
     {
         SchemaRegistry.Global.Register(new("http://dotnet.github.io/docfx/schemas/v1.0/schema.json#"), MetaSchemas.Draft7);
@@ -25,11 +31,7 @@ public SchemaValidator(string json)
     public void Validate(object obj)
     {
         var json = JsonSerializer.Serialize(obj);
-        var result = _schema.Evaluate(JsonDocument.Parse(json), new EvaluationOptions
-        {
-            ValidateAgainstMetaSchema = false,
-            OutputFormat = OutputFormat.List,
-        });
+        var result = _schema.Evaluate(JsonDocument.Parse(json), DefaultOptions);
 
         if (result.IsValid)
             return;

src/Docfx.Build/HostServiceCreator.cs

@@ -63,8 +63,12 @@ public virtual (FileModel model, bool valid) Load(
             {
                 if (e is not DocumentException)
                 {
+                    var message = e is ArgumentException or NullReferenceException
+                        ? e.ToString()
+                        : e.Message;
+
                     Logger.LogError(
-                        $"Unable to load file '{file.File}' via processor '{processor.Name}': {e.Message}",
+                        $"Unable to load file '{file.File}' via processor '{processor.Name}': {message}",
                         code: ErrorCodes.Build.InvalidInputFile);
                 }
                 return (null, false);

src/Docfx.Dotnet/Filters/ConfigFilterRuleItemUnion.cs

@@ -54,7 +54,10 @@ public ConfigFilterRuleItem Rule
             }
 
             // If kind is not specified for exclude. Set `ExtendedSymbolKind.Type` as default kind.
-            Exclude.Kind ??= ExtendedSymbolKind.Type | ExtendedSymbolKind.Member;
+            if (Exclude != null)
+            {
+                Exclude.Kind ??= ExtendedSymbolKind.Type | ExtendedSymbolKind.Member;
+            }
 
             return Exclude;
         }

src/Docfx.Dotnet/MetadataJsonConfig.cs

@@ -118,10 +118,11 @@ internal class MetadataJsonItemConfig
     [JsonPropertyName("shouldSkipMarkup")]
     public bool? ShouldSkipMarkup { get; set; }
 
-    [JsonProperty("raw")]
-    [JsonPropertyName("raw")]
-    public bool? Raw { get; set; }
-
+    /// <summary>
+    /// Specify additinal assembly reference files.
+    /// This settings is used when generating metadata from DLLs or source files.
+    /// Solution or project file-based metadata generation does not use this property.
+    /// </summary>
     [JsonProperty("references")]
     [JsonPropertyName("references")]
     public FileMapping References { get; set; }

src/Docfx.Dotnet/Parsers/XmlComment.cs

@@ -112,6 +112,10 @@ public static XmlComment Parse(string xml, XmlCommentParserContext context = nul
         }
         try
         {
+            // Format xml with indentation.
+            // It's needed to fix issue (https://github.com/dotnet/docfx/issues/9736)
+            xml = XElement.Parse(xml).ToString(SaveOptions.None);
+
             return new XmlComment(xml, context ?? new());
         }
         catch (XmlException)

src/Docfx.MarkdigEngine.Extensions/MarkdownExtensions.cs

@@ -4,6 +4,7 @@
 using Markdig;
 using Markdig.Extensions.AutoIdentifiers;
 using Markdig.Extensions.CustomContainers;
+using Markdig.Extensions.Emoji;
 using Markdig.Extensions.EmphasisExtras;
 using Markdig.Parsers;
 
@@ -17,7 +18,7 @@ public static MarkdownPipelineBuilder UseDocfxExtensions(
     {
         return pipeline
             .UseMathematics()
-            .UseEmphasisExtras()
+            .UseEmphasisExtras(EmphasisExtraOptions.Strikethrough)
             .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
             .UseMediaLinks()
             .UsePipeTables()
@@ -56,9 +57,34 @@ public static MarkdownPipelineBuilder UseOptionalExtensions(
             return pipeline;
         }
 
+        ReplaceExistingExtensions();
+
         pipeline.Configure(string.Join("+", optionalExtensions));
 
         return pipeline;
+
+        // Some markdig extensions are added by UseDocfxExtensions with non-default settings.
+        // This methods replace these extensions with default settings.
+        void ReplaceExistingExtensions()
+        {
+            // AutoIdentifierExtension
+            if (optionalExtensions.Contains("autoidentifiers", StringComparer.OrdinalIgnoreCase))
+            {
+                pipeline.Extensions.Replace<AutoIdentifierExtension>(new AutoIdentifierExtension(AutoIdentifierOptions.Default));
+            }
+
+            // EmphasisExtraExtension
+            if (optionalExtensions.Contains("emphasisextras", StringComparer.OrdinalIgnoreCase))
+            {
+                pipeline.Extensions.Replace<EmphasisExtraExtension>(new EmphasisExtraExtension(EmphasisExtraOptions.Default));
+            }
+
+            // EmojiExtension
+            if (optionalExtensions.Contains("emojis", StringComparer.OrdinalIgnoreCase))
+            {
+                pipeline.Extensions.Replace<EmojiExtension>(new EmojiExtension(EmojiMapping.DefaultEmojisAndSmileysMapping));
+            }
+        }
     }
 
     private static MarkdownPipelineBuilder RemoveUnusedExtensions(this MarkdownPipelineBuilder pipeline)

templates/common/ManagedReference.common.js

@@ -261,4 +261,9 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
 
     return array;
   }
+  if(vm.syntax.typeParameters) {
+    vm.syntax.typeParameters.forEach(item => {
+      item.description = item.description || "";
+    });
+  }
 }