.editorconfig

@@ -78,7 +78,8 @@ csharp_prefer_static_local_function = true:suggestion
 dotnet_diagnostic.IDE0010.severity = suggestion                                    # IDE0010: Add missing cases to switch statement
 dotnet_style_object_initializer = true:suggestion                                  # IDE0017: Use object initializers
 csharp_style_inlined_variable_declaration = true:suggestion                        # IDE0018: Inline variable declaration
-dotnet_style_collection_initializer = true:suggestion                              # IDE0028: Use collection initializers
+dotnet_style_collection_initializer = true:suggestion                              # IDE0028: Use collection initializers or expressions
+dotnet_style_prefer_collection_expression = true:suggestion                        # IDE0028: Use collection initializers or expressions
 dotnet_style_prefer_auto_properties = true:suggestion                              # IDE0032: Use auto-implemented property
 dotnet_style_explicit_tuple_names = true:suggestion                                # IDE0033: Use explicitly provided tuple name
 csharp_prefer_simple_default_expression = true:suggestion                          # IDE0034: Simplify default expression
@@ -153,7 +154,7 @@ dotnet_style_namespace_match_folder = true:suggestion                   # IDE013
 dotnet_diagnostic.IDE0001.severity = suggestion # IDE0001: Simplify name
 dotnet_diagnostic.IDE0002.severity = suggestion # IDE0002: Simplify member access
 dotnet_diagnostic.IDE0004.severity = suggestion # IDE0004: Remove unnecessary cast
-dotnet_diagnostic.IDE0005.severity = suggestion # IDE0005: Remove unnecessary import
+dotnet_diagnostic.IDE0005.severity = warning    # IDE0005: Remove unnecessary import
 dotnet_diagnostic.IDE0035.severity = suggestion # IDE0035: Remove unreachable code
 dotnet_diagnostic.IDE0051.severity = suggestion # IDE0051: Remove unused private member
 dotnet_diagnostic.IDE0052.severity = suggestion # IDE0052: Remove unread private member

.github/codecov.yml

@@ -0,0 +1,11 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+comment: false
+github_checks:
+  annotations: false

.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
 jobs:
   test:
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
@@ -45,6 +46,12 @@ jobs:
       env:
         PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
 
+    - uses: codecov/codecov-action@v5
+      if: matrix.os == 'ubuntu-latest'
+      with:
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}
+
     - run: echo "DOTNET_DbgEnableMiniDump=1" >> $GITHUB_ENV
       if: matrix.os == 'ubuntu-latest'
 

.github/workflows/lint.yml

@@ -0,0 +1,44 @@
+name: lint
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: github.event.pull_request.draft == false   
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            9.x
+
+      - name: Run `dotnet format` command
+        run: |
+          dotnet restore
+          dotnet format --no-restore --verify-no-changes
+
+      - name: Report failures as Job Summary
+        if: ${{ failure() }}
+        shell: pwsh
+        run: |
+          $content = '
+          ## Failed to run the `lint.yml` workflow
+          To fix workflow errors. Please follow the steps below.
+           1. Run `dotnet format` command.
+           2. Commit changes as separated commit.
+           3. Push changes to source branch of PR.
+          '
+          Write-Output $content >> $env:GITHUB_STEP_SUMMARY

.github/workflows/nightly.yml

@@ -11,6 +11,7 @@ jobs:
   publish-github-packages:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     permissions:
       packages: write
     steps:

.github/workflows/reports.yml

@@ -15,6 +15,7 @@ permissions:
 jobs:
   report:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     if: ${{ github.event.workflow_run.conclusion == 'success' || github.event.workflow_run.conclusion == 'failure' }}
     steps:
     - name: Create Test Report

.github/workflows/snapshot.yml

@@ -11,6 +11,7 @@ on:
 jobs:
   snapshot:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     environment: ci
     strategy:
       fail-fast: false

Directory.Build.props

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
     <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
-    <TargetFrameworks Condition="'$(DOCFX_PREVIEW_BUILD)' == 'true'">net8.0;net9.0</TargetFrameworks> 
+    <TargetFrameworks Condition="'$(DOCFX_PREVIEW_BUILD)' == 'true'">net8.0;net9.0</TargetFrameworks>
     <LangVersion>Preview</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
@@ -29,8 +29,8 @@
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources> 
-  
+    <EmbedUntrackedSources>true</EmbedUntrackedSources>
+
     <Authors>.NET Foundation and Contributors</Authors>
     <Copyright>Copyright (c) .NET Foundation and Contributors</Copyright>
     <Description>Technical documentation tool with markdown, API docs for .NET, REST API and more.</Description>
@@ -44,13 +44,6 @@
     <None Include="$(MSBuildThisFileDirectory)\README.md" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
-  <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
-    </PackageReference>
-  </ItemGroup>
-
   <!-- Remove Node.js runtime dependencies that used by playwright -->
   <Target Name="RemoveNodeJsRuntimes" AfterTargets="CopyPlaywrightFilesToOutput">
     <ItemGroup>

Directory.Packages.props

@@ -4,13 +4,12 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
   <ItemGroup>
-    <PackageVersion Include="HtmlAgilityPack" Version="1.11.71" />
-    <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
-    <PackageVersion Include="Jint" Version="4.1.0" />
-    <PackageVersion Include="JsonSchema.Net" Version="7.2.3" />
-    <PackageVersion Include="Markdig" Version="0.38.0" />
-    <PackageVersion Include="Microsoft.Playwright" Version="1.48.0" />
-    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <PackageVersion Include="HtmlAgilityPack" Version="1.11.72" />
+    <PackageVersion Include="ICSharpCode.Decompiler" Version="9.0.0.7889" />
+    <PackageVersion Include="Jint" Version="4.2.0" />
+    <PackageVersion Include="JsonSchema.Net" Version="7.3.3" />
+    <PackageVersion Include="Markdig" Version="0.40.0" />
+    <PackageVersion Include="Microsoft.Playwright" Version="1.50.0" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="OneOf" Version="3.0.271" />
     <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
@@ -19,32 +18,31 @@
     <PackageVersion Include="Spectre.Console" Version="0.49.1" />
     <PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
     <PackageVersion Include="Stubble.Core" Version="1.10.8" />
-    <PackageVersion Include="System.Collections.Immutable" Version="9.0.0" />
-    <PackageVersion Include="System.Composition" Version="9.0.0" />
-    <PackageVersion Include="System.Formats.Asn1" Version="9.0.0" />
-    <PackageVersion Include="System.Text.Json" Version="9.0.0" />
-    <PackageVersion Include="YamlDotNet" Version="15.3.0" />
+    <PackageVersion Include="System.Collections.Immutable" Version="9.0.2" />
+    <PackageVersion Include="System.Composition" Version="9.0.2" />
+    <PackageVersion Include="System.Formats.Asn1" Version="9.0.2" />
+    <PackageVersion Include="System.Text.Json" Version="9.0.2" />
+    <PackageVersion Include="YamlDotNet" Version="16.3.0" />
   </ItemGroup>
 
+  <!-- .slnx solution format is supported Microsoft.Build 17.13.9 or later. -->
   <ItemGroup>
-    <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.11.0" />
+    <PackageVersion Include="Microsoft.Build" Version="[17.11.4]" Condition="'$(TargetFramework)' == 'net8.0'"/>
+    <PackageVersion Include="Microsoft.Build" Version="17.13.9"   Condition="'$(TargetFramework)' != 'net8.0'"/>
   </ItemGroup>
 
   <ItemGroup>
-    <!-- Test only -->
-    <PackageVersion Include="coverlet.collector" Version="6.0.2" />
-    <PackageVersion Include="FluentAssertions" Version="6.12.2" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
-    <PackageVersion Include="Verify.DiffPlex" Version="3.1.2" />
-    <PackageVersion Include="Verify.Xunit" Version="28.3.2" />
-    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
-    <PackageVersion Include="xunit" Version="2.9.2" />
+    <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.12.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.12.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <GlobalPackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
   </ItemGroup>
 </Project>

Dockerfile

@@ -7,7 +7,7 @@ ENV PATH="${PATH}:/root/.dotnet/tools"
 ENV PLAYWRIGHT_NODEJS_PATH="/usr/bin/node"
 
 # Set target docfx version.
-ARG DOCFX_VERSION=2.78.1
+ARG DOCFX_VERSION=2.78.2
 
 # Install DocFX as a dotnet tool.
 RUN dotnet tool install docfx -g --version ${DOCFX_VERSION} && \
@@ -25,4 +25,4 @@ RUN apt-get install -y -qq --update --no-install-recommends nodejs && \
 WORKDIR /opt/prj
 VOLUME [ "/opt/prj" ]
 
-ENTRYPOINT [ "docfx" ]
+ENTRYPOINT [ "docfx" ]

docfx.sln

@@ -15,6 +15,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{926A0726-B806-4215-82EF-AF8E22D0FACF}"
 	ProjectSection(SolutionItems) = preProject
 		test\Directory.Build.props = test\Directory.Build.props
+		test\Directory.Packages.props = test\Directory.Packages.props
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "docfx", "src\docfx\docfx.csproj", "{EF53214F-BA98-4026-BEED-CF771865C312}"
@@ -97,6 +98,13 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Docfx.Build.OverwriteDocume
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Docfx.Build.OverwriteDocuments.Tests", "test\Docfx.Build.OverwriteDocuments.Tests\Docfx.Build.OverwriteDocuments.Tests.csproj", "{CAECA6C3-3317-4E6E-8927-9186857B23E8}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
+	ProjectSection(SolutionItems) = preProject
+		.editorconfig = .editorconfig
+		Directory.Build.props = Directory.Build.props
+		Directory.Packages.props = Directory.Packages.props
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

docs/index.md

@@ -131,7 +131,7 @@ If you want to use prerelease version, you can install package with following st
 2. Login to GitHub with additional scope request
 
     ```pwsh
-    gh auth login --scopes "read:packages" --host github.com
+    gh auth login --scopes "read:packages" --hostname github.com
     ```
 
 3. Follow the instructions and complete the login steps.

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

@@ -77,6 +77,10 @@ Run `docfx metadata --help` or `docfx -h` to get a list of all available options
 
   Disable the default API filter (default filter only generate public or protected APIs).
 
+- **--noRestore**
+
+  Do not run `dotnet restore` before building the projects.
+
 - **--namespaceLayout**
 
   Determines the namespace layout in table of contents.

samples/seed/docfx.json

@@ -70,7 +70,7 @@
       { "files": [ "**" ], "src": "obj/md", "dest": "md" },
       { "files": [ "**" ], "src": "obj/apipage", "dest": "apipage" },
       { "files": [ "articles/**/*.{md,yml}", "*.md", "toc.yml", "restapi/**" ] },
-      { "files": [ "pdf/**" ] }
+      { "files": [ "pdf/*.{md,yml}" ] }
     ],
     "resource": [
       {

samples/seed/dotnet/assembly/BuildFromAssembly.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>

samples/seed/dotnet/project/Project/Inheritdoc.cs

@@ -108,4 +108,41 @@ public class Class2 : Class1<bool>
             public override bool TestMethod1(bool parm1, int parm2) => false;
         }
     }
-}
+
+    // Issue #9736 #9495 #9754
+    public class Issue9736
+    {
+        public interface IJsonApiOptions
+        {
+            /// <summary>
+            /// Whether to use relative links for all resources. <c>false</c> by default.
+            /// </summary>
+            /// <example>
+            /// <code><![CDATA[
+            /// options.UseRelativeLinks = true;
+            /// ]]></code>
+            /// <code><![CDATA[
+            /// {
+            ///   "type": "articles",
+            ///   "id": "4309",
+            ///   "relationships": {
+            ///      "author": {
+            ///        "links": {
+            ///          "self": "/api/shopping/articles/4309/relationships/author",
+            ///          "related": "/api/shopping/articles/4309/author"
+            ///        }
+            ///      }
+            ///   }
+            /// }
+            /// ]]></code>
+            /// </example>
+            bool UseRelativeLinks { get; }
+        }
+
+        public sealed class JsonApiOptions : IJsonApiOptions
+        {
+            /// <inheritdoc />
+            public bool UseRelativeLinks { get; set; }
+        }
+    }
+}

src/Docfx.App/Config/BuildJsonConfig.cs

@@ -72,7 +72,7 @@ internal class BuildJsonConfig
     /// </summary>
     [JsonProperty("globalMetadataFiles")]
     [JsonPropertyName("globalMetadataFiles")]
-    public ListWithStringFallback GlobalMetadataFiles { get; set; } = new();
+    public ListWithStringFallback GlobalMetadataFiles { get; set; } = [];
 
     /// <summary>
     /// Metadata that applies to some specific files.
@@ -99,7 +99,7 @@ internal class BuildJsonConfig
     /// </summary>
     [JsonProperty("template")]
     [JsonPropertyName("template")]
-    public ListWithStringFallback Template { get; set; } = new();
+    public ListWithStringFallback Template { get; set; } = [];
 
     /// <summary>
     /// The themes applied to the documentation.
@@ -123,7 +123,7 @@ internal class BuildJsonConfig
     ///  </example>
     [JsonProperty("postProcessors")]
     [JsonPropertyName("postProcessors")]
-    public ListWithStringFallback PostProcessors { get; set; } = new();
+    public ListWithStringFallback PostProcessors { get; set; } = [];
 
     /// <summary>
     /// Run in debug mode. With debug mode, raw model and view model will be exported

src/Docfx.App/Config/FileMetadataPairs.cs

@@ -39,7 +39,7 @@ public FileMetadataPairs(IEnumerable<FileMetadataPairsItem> items)
     /// </summary>
     public FileMetadataPairs(FileMetadataPairsItem item)
     {
-        _items = new List<FileMetadataPairsItem> { item };
+        _items = [item];
     }
 
     /// <summary>

src/Docfx.App/Config/FileMetadataPairsConverter.SystemTextJson.cs

@@ -1,7 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-using System.Linq;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using Docfx.Common;