feat: add TOC order for toc_rel pick order (#9406)

docs/docs/pdf.md

@@ -48,6 +48,17 @@ In case the TOC file is auto-generated, use [file metadata](./config.md#metadata
 }
 ```
 
+You can create a single PDF file using a dedicated PDF TOC containing all articles with [Nested TOCs](./table-of-contents.md#nested-tocs) and set `order` to a bigger value to prevent the PDF TOC from appearing on the website.
+
+```yaml
+order: 200
+items:
+- name: Section 1
+  href: section-1/toc.yml
+- name: Section 2
+  href: section-2/toc.yml
+```
+
 ## PDF Metadata
 
 These metadata applies to TOC files that controls behaviors of PDF generation.
@@ -84,7 +95,7 @@ To preview PDF rendering result, print the HTML page in the web browser, or set
 
 The site template adds a default margin and removes background graphics for pages in print mode. Use `@page { margin: 0 }` to remove the default margin and use `print-color-adjust: exact` to keep background graphics for cover pages.
 
-See [this example](https://raw.githubusercontent.com/dotnet/docfx/main/samples/seed/pdf.md) on a PDF cover page that fills the whole page with background graphics:
+See [this example](https://raw.githubusercontent.com/dotnet/docfx/main/samples/seed/pdf/cover.md) on a PDF cover page that fills the whole page with background graphics:
 
 ![Alt text](./media/pdf-cover-page.png)
 

docs/docs/table-of-contents.md

@@ -28,6 +28,16 @@ The YAML document is a tree of TOC nodes, each of which has these properties:
 - `uid`: The uid of the article. Can be used instead of `href`.
 - `expanded`: Expand children on load, only works if the template is `modern`.
 
+When an article is referenced by a TOC through `href`, the corresponding TOC appears when viewing that article. If multiple TOCs reference the same article, or the article isn't referenced by any TOC, the nearest TOC with the least amount of directory jumps is picked.
+
+The `order` property can customize this pick logic, TOCs with a smaller order value are picked first. The default order is 0.
+
+```yml
+order: 100
+items:
+- ...
+```
+
 ## Nested TOCs
 
 To nest a TOC within another TOC, set the `href` property to point to the `toc.yml` file that you want to nest. You can also use this structure as a way to reuse a TOC structure in one or more TOC files.
@@ -63,6 +73,8 @@ Reference
 ├─ System.Float
 ```
 
+Nested TOCs by default have `order` set to `100` to let containing TOCs take precedence.
+
 ## Reference TOCs
 
 To reference another TOC without embeding it to a parent TOC using nested TOCs, set the `href` property to point to the directory that you want to reference and end the string with `/`, this will generate a link pointing to the first article in the referenced TOC.

samples/seed/articles/toc.yml

@@ -1,5 +1,5 @@
 pdfFileName: seed.pdf
-pdfCoverPage: pdf.html
+pdfCoverPage: pdf/cover.html
 items:
 - name: Getting Started
   href: docfx_getting_started.md

samples/seed/docfx.json

@@ -66,10 +66,10 @@
   "build": {
     "content": [
       { "files": [ "**/*.yml" ], "src": "obj/api", "dest": "api" },
-      { "files": [ "**/*.yml" ], "src": "obj/apipage", "dest": "apipage" },
       { "files": [ "**" ], "src": "obj/md", "dest": "md" },
       { "files": [ "**" ], "src": "obj/apipage", "dest": "apipage" },
-      { "files": [ "articles/**/*.{md,yml}", "*.md", "toc.yml", "restapi/**", "md/**", "md2/**" ] }
+      { "files": [ "articles/**/*.{md,yml}", "*.md", "toc.yml", "restapi/**" ] },
+      { "files": [ "pdf/**" ] }
     ],
     "resource": [
       {

samples/seed/pdf/toc.yml

@@ -1,4 +1,6 @@
-- name: Articles
+order: 200
+items:
+- name: Articles
   href: ../articles/toc.yml
 - name: API Documentation
   href: ../obj/api/toc.yml

src/Docfx.Build/SystemMetadataGenerator.cs

@@ -11,7 +11,7 @@ namespace Docfx.Build.Engine;
 internal sealed class SystemMetadataGenerator
 {
     private readonly IDocumentBuildContext _context;
-    private readonly IEnumerable<FileInfo> _toc;
+    private readonly Dictionary<string, FileInfo> _toc;
 
     public SystemMetadataGenerator(IDocumentBuildContext context)
     {
@@ -21,9 +21,10 @@ public SystemMetadataGenerator(IDocumentBuildContext context)
 
         // Order toc files by the output folder depth
         _toc = context.GetTocInfo()
-            .Select(s => new FileInfo(s.TocFileKey, context.GetFilePath(s.TocFileKey)))
+            .Select(s => new FileInfo(s.Order, s.TocFileKey, context.GetFilePath(s.TocFileKey)))
             .Where(s => s.RelativePath != null)
-            .OrderBy(s => s.RelativePath.SubdirectoryCount);
+            .OrderBy(s => s.RelativePath.SubdirectoryCount)
+            .ToDictionary(s => s.Key);
     }
 
     public SystemMetadata Generate(InternalManifestItem item)
@@ -68,7 +69,7 @@ public SystemMetadata Generate(InternalManifestItem item)
         // 2. The algorithm of toc current article belongs to:
         //    a. If toc can be found in TocMap, return that toc
         //    b. Elsewise, get the nearest toc, **nearest** means nearest toc in **OUTPUT** folder
-        var parentTocFiles = _context.GetTocFileKeySet(key)?.Select(s => new FileInfo(s, _context.GetFilePath(s)));
+        var parentTocFiles = _context.GetTocFileKeySet(key)?.Select(s => _toc[s]);
         var parentToc = GetNearestToc(parentTocFiles, file) ?? GetDefaultToc(key);
 
         if (parentToc != null)
@@ -90,7 +91,7 @@ public SystemMetadata Generate(InternalManifestItem item)
 
     private void GetRootTocFromOutputRoot(SystemMetadata attrs, RelativePath file)
     {
-        var rootToc = _toc.FirstOrDefault();
+        var rootToc = _toc.Values.FirstOrDefault();
         if (rootToc != null)
         {
             var rootTocPath = rootToc.RelativePath.RemoveWorkingFolder();
@@ -116,11 +117,13 @@ private FileInfo GetDefaultToc(string fileKey)
 
         // MakeRelativeTo calculates how to get file "s" from "outputPath"
         // The standard for being the toc of current file is: Relative directory is empty or ".."s only
-        var parentTocs = _toc
+        var parentTocs = _toc.Values
             .Select(s => new { rel = s.RelativePath.MakeRelativeTo(outputPath), info = s })
             .Where(s => s.rel.SubdirectoryCount == 0)
-            .OrderBy(s => s.rel.ParentDirectoryCount)
+            .OrderBy(s => s.info.Order)
+            .ThenBy(s => s.rel.ParentDirectoryCount)
             .Select(s => s.info);
+
         return parentTocs.FirstOrDefault();
     }
 
@@ -139,9 +142,8 @@ private static FileInfo GetNearestToc(IEnumerable<FileInfo> tocFiles, RelativePa
         return (from toc in tocFiles
                 where toc.RelativePath != null
                 let relativePath = toc.RelativePath.RemoveWorkingFolder() - file
-                orderby relativePath.SubdirectoryCount, relativePath.ParentDirectoryCount, toc.FilePath, toc.Key
-                select toc)
-            .FirstOrDefault();
+                orderby toc.Order, relativePath.SubdirectoryCount, relativePath.ParentDirectoryCount, toc.FilePath, toc.Key
+                select toc).FirstOrDefault();
     }
 
     private static string GetFileKey(string key)
@@ -150,16 +152,19 @@ private static string GetFileKey(string key)
         return RelativePath.NormalizedWorkingFolder + key;
     }
 
-    private sealed class FileInfo
+    class FileInfo
     {
-        public string Key { get; set; }
+        public int Order { get; }
+
+        public string Key { get; }
 
-        public string FilePath { get; set; }
+        public string FilePath { get; }
 
-        public RelativePath RelativePath { get; set; }
+        public RelativePath RelativePath { get; }
 
-        public FileInfo(string key, string filePath)
+        public FileInfo(int order, string key, string filePath)
         {
+            Order = order;
             Key = key;
             FilePath = filePath;
             RelativePath = (RelativePath)filePath;

src/Docfx.Build/TableOfContents/TocDocumentProcessor.cs

@@ -186,18 +186,7 @@ private void RegisterTocToContext(TocItemViewModel toc, FileModel model, IDocume
         // Add current folder to the toc mapping, e.g. `a/` maps to `a/toc`
         var directory = ((RelativePath)key).GetPathFromWorkingFolder().GetDirectoryPath();
         context.RegisterToc(key, directory);
-
-        var tocInfo = new TocInfo(key);
-        if (toc.Homepage != null)
-        {
-            if (PathUtility.IsRelativePath(toc.Homepage))
-            {
-                var pathToRoot = ((RelativePath)model.File + (RelativePath)HttpUtility.UrlDecode(toc.Homepage)).GetPathFromWorkingFolder();
-                tocInfo.Homepage = pathToRoot;
-            }
-        }
-
-        context.RegisterTocInfo(tocInfo);
+        context.RegisterTocInfo(new() { TocFileKey = key, Order = toc.Order ?? 0 });
     }
 
     private void RegisterTocMapToContext(TocItemViewModel item, FileModel model, IDocumentBuildContext context)

src/Docfx.Build/TableOfContents/TocHelper.cs

@@ -13,7 +13,7 @@ public static class TocHelper
 {
     private static readonly YamlDeserializerWithFallback _deserializer =
         YamlDeserializerWithFallback.Create<TocViewModel>()
-        .WithFallback<TocRootViewModel>();
+        .WithFallback<TocItemViewModel>();
 
     public static List<FileModel> ResolveToc(ImmutableList<FileModel> models, IHostService host)
     {
@@ -32,13 +32,13 @@ public static List<FileModel> ResolveToc(ImmutableList<FileModel> models, IHostS
 
         foreach (var model in models)
         {
-            // If the TOC file is referenced by other TOC, remove it from the collection
+            // If the TOC file is referenced by other TOC, decrease the score
             var tocItemInfo = tocCache[model.OriginalFileAndType.FullPath];
-            if (!tocItemInfo.IsReferenceToc)
-            {
-                model.Content = tocItemInfo.Content;
-                nonReferencedTocModels.Add(model);
-            }
+            if (tocItemInfo.IsReferenceToc && tocItemInfo.Content.Order is null)
+                tocItemInfo.Content.Order = 100;
+
+            model.Content = tocItemInfo.Content;
+            nonReferencedTocModels.Add(model);
         }
 
         return nonReferencedTocModels;
@@ -65,61 +65,28 @@ public static TocItemViewModel LoadSingleToc(string file)
         {
             if (fileType == TocFileType.Markdown)
             {
-                return new TocItemViewModel
+                return new()
                 {
                     Items = MarkdownTocReader.LoadToc(EnvironmentContext.FileAbstractLayer.ReadAllText(file), file)
                 };
             }
             else if (fileType == TocFileType.Yaml)
             {
-                return LoadYamlToc(file);
+                return _deserializer.Deserialize(file) switch
+                {
+                    TocViewModel vm => new() { Items = vm },
+                    TocItemViewModel root => root,
+                    _ => throw new NotSupportedException($"{file} is not a valid TOC file."),
+                };
             }
         }
         catch (Exception e)
         {
-            var message = $"{file} is not a valid TOC File: {e.Message}";
+            var message = $"{file} is not a valid TOC File: {e}";
             Logger.LogError(message, code: ErrorCodes.Toc.InvalidTocFile);
             throw new DocumentException(message, e);
         }
 
         throw new NotSupportedException($"{file} is not a valid TOC file, supported TOC files should be either \"{Constants.TableOfContents.MarkdownTocFileName}\" or \"{Constants.TableOfContents.YamlTocFileName}\".");
     }
-
-    public static TocItemViewModel LoadYamlToc(string file)
-    {
-#if NET7_0_OR_GREATER
-        ArgumentException.ThrowIfNullOrEmpty(file);
-#else
-        if (string.IsNullOrEmpty(file))
-        {
-            throw new ArgumentNullException(nameof(file));
-        }
-#endif
-
-        object obj;
-        try
-        {
-            obj = _deserializer.Deserialize(file);
-        }
-        catch (Exception ex)
-        {
-            throw new NotSupportedException($"{file} is not a valid TOC file, detail: {ex}.", ex);
-        }
-        if (obj is TocViewModel vm)
-        {
-            return new TocItemViewModel
-            {
-                Items = vm,
-            };
-        }
-        if (obj is TocRootViewModel root)
-        {
-            return new TocItemViewModel
-            {
-                Items = root.Items,
-                Metadata = root.Metadata,
-            };
-        }
-        throw new NotSupportedException($"{file} is not a valid TOC file.");
-    }
 }

src/Docfx.DataContracts.Common/TocItemViewModel.cs

@@ -118,6 +118,11 @@ public string NameForVB
     [JsonPropertyName(Constants.PropertyName.TopicUid)]
     public string TopicUid { get; set; }
 
+    [YamlMember(Alias = "order")]
+    [JsonProperty("order")]
+    [JsonPropertyName("order")]
+    public int? Order { get; set; }
+
     [YamlIgnore]
     [Newtonsoft.Json.JsonIgnore]
     [System.Text.Json.Serialization.JsonIgnore]

src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs

@@ -53,7 +53,7 @@ void ResolveAndExportYamlMetadata(
             // generate toc.yml
             model.TocYamlViewModel.Type = MemberType.Toc;
 
-            var tocViewModel = new TocRootViewModel
+            var tocViewModel = new TocItemViewModel
             {
                 Metadata = new() { ["memberLayout"] = config.MemberLayout },
                 Items = model.TocYamlViewModel.ToTocViewModel(),

src/Docfx.Plugins/TocInfo.cs

@@ -5,11 +5,7 @@ namespace Docfx.Plugins;
 
 public class TocInfo
 {
-    public string TocFileKey { get; }
-    public string Homepage { get; set; }
+    public string TocFileKey { get; init; }
 
-    public TocInfo(string tocFileKey)
-    {
-        TocFileKey = tocFileKey;
-    }
+    public int Order { get; init; }
 }

src/docfx/Properties/launchSettings.json

@@ -13,7 +13,7 @@
     // Run `docfx build` command.
     "docfx build": {
       "commandName": "Project",
-      "commandLineArgs": "build ../../samples/seed/docfx.json",
+      "commandLineArgs": "build ../../samples/seed/docfx.json --serve",
       "workingDirectory": ".",
       "environmentVariables": {
       }

test/Docfx.Build.Tests/TocDocumentProcessorTest.cs

@@ -529,9 +529,9 @@ public void ProcessYamlTocWithReferencedTocShouldSucceed()
 
         AssertTocEqual(expectedModel, model);
 
-        // Referenced TOC File should not exist
+        // Referenced TOC File should exist
         var referencedTocPath = Path.Combine(_outputFolder, Path.ChangeExtension(sub1tocmd, RawModelFileExtension));
-        Assert.False(File.Exists(referencedTocPath));
+        Assert.True(File.Exists(referencedTocPath));
     }
 
     [Fact]
@@ -766,7 +766,7 @@ public void LoadBadTocYamlFileShouldGiveLineNumber()
       href: x2.md";
         var toc = _fileCreator.CreateFile(content, FileType.YamlToc);
         var ex = Assert.Throws<DocumentException>(() => TocHelper.LoadSingleToc(toc));
-        Assert.Equal("toc.yml is not a valid TOC File: toc.yml is not a valid TOC file, detail: (Line: 3, Col: 10, Idx: 22) - (Line: 3, Col: 10, Idx: 22): While scanning a plain scalar value, found invalid mapping..", ex.Message);
+        Assert.Equal("toc.yml is not a valid TOC File: (Line: 3, Col: 10, Idx: 22) - (Line: 3, Col: 10, Idx: 22): While scanning a plain scalar value, found invalid mapping.", ex.Message);
     }
 
     [Fact]
@@ -787,7 +787,7 @@ public void LoadTocYamlWithEmptyNodeShouldSucceed()
         // Assert
         var outputRawModelPath = Path.GetFullPath(Path.Combine(_outputFolder, Path.ChangeExtension(file, RawModelFileExtension)));
         Assert.True(File.Exists(outputRawModelPath));
-        var model = JsonUtility.Deserialize<TocRootViewModel>(outputRawModelPath);
+        var model = JsonUtility.Deserialize<TocItemViewModel>(outputRawModelPath);
         Assert.Single(model.Items); // empty node is removed
     }
 

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

@@ -1,4 +1,5 @@
 {
+  "order": 100.0,
   "items": [
     {
       "name": "BuildFromAssembly",