Unable to build with template

[neilpendlington]

Using docfx version 2.75.2+fe673ecea2ac444a4fd480e6cfcf605c78614385 (latest from github), and discordfx v0.5, I'm getting an error preventing the build.

Project folder is C:\Projects\technical-guides\content so in a command prompt I change to this folder and then run ..\build\docfx\docfx.exe build (the docfx executable lives relative to the current folder).

The discordfx template folder is in C:\Projects\technical-guides\content\templates\discordfx. And the error I'm seeing when trying to build is below. I can build fine with the default themes so I wonder if there's a compatibility issue?

Searching custom plugins in directory C:\Projects\technical-guides\build\docfx\...
Post processor ExtractSearchIndex loaded.
No files are found with glob pattern images/**, excluding <none>, under directory "C:\Projects\technical-guides\content"
7 plug-in(s) loaded.
Building 3 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>ValidateConceptualDocumentMetadata)...
Building 2 file(s) in TocDocumentProcessor(BuildTocDocument)...
Applying templates to 5 model(s)...
C:\Projects\technical-guides\content\toc.yml: error ApplyTemplateRendererError: Error applying template "toc.html" generated from "toc.yml". To get the detailed view model, please run docfx with debug mode --debug. You have reached the maximum recursion limit of 256.
C:\Projects\technical-guides\content\docs\toc.yml: error ApplyTemplateRendererError: Error applying template "toc.html" generated from "docs/toc.yml". To get the detailed view model, please run docfx with debug mode --debug. You have reached the maximum recursion limit of 256.
DocumentException: Error applying template "toc.html" generated from "toc.yml". To get the detailed view model, please
run docfx with debug mode --debug. You have reached the maximum recursion limit of 256.
     DocumentException: Error applying template "toc.html" generated from "toc.yml". To get the detailed view model,
     please run docfx with debug mode --debug. You have reached the maximum recursion limit of 256.
          StubbleException: You have reached the maximum recursion limit of 256.
            at object Render(BlockToken block, Context context)
            at void Write(StringRender renderer, SectionToken obj, Context context)
            at void Write(RendererBase<TContext> renderer, MustacheToken obj, TContext context)
            at void Write<T>(T obj, TContext context)
            at object Render(BlockToken block, Context context)
            at void Write(StringRender renderer, PartialToken obj, Context context)

<snip>

            at string Render(string template, object view)
            at string Render(object model) in MustacheTemplateRenderer.cs:55
            at string Render(object model) in RendererWithResourcePool.cs:36
            at string Transform(object model) in Template.cs:110
            at ManifestItem Transform(InternalManifestItem item) in TemplateModelTransformer.cs:121
       at ManifestItem Transform(InternalManifestItem item) in TemplateModelTransformer.cs:138
       at void <ProcessCore>b__0(InternalManifestItem item) in TemplateProcessor.cs:194
       at void <RunAll>b__0(TElement s) in DocumentExceptionExtensions.cs:80
  at void RunAll<TElement>(IEnumerable<TElement> elements, Action<TElement> action, int parallelism) in
     DocumentExceptionExtensions.cs:89
  at void RunAll<TElement>(IReadOnlyList<TElement> elements, Action<TElement> action, int parallelism) in
     DocumentExceptionExtensions.cs:60
  at List<ManifestItem> ProcessCore(List<InternalManifestItem> items, ApplyTemplateSettings settings,
     IDictionary<string, object> globals) in TemplateProcessor.cs:189
  at List<ManifestItem> Process(List<InternalManifestItem> manifest, ApplyTemplateSettings settings, IDictionary<string,
     object> globals) in TemplateProcessor.cs:88
  at List<ManifestItem> ProcessTemplate() in ManifestProcessor.cs:182
  at void Process() in ManifestProcessor.cs:53
  at void Handle(List<HostService> hostServices, int maxParallelism) in LinkPhaseHandler.cs:32
  at Manifest Build(DocumentBuildParameters parameters, IMarkdownService markdownService) in SingleDocumentBuilder.cs:67
  at void Build(IList<DocumentBuildParameters> parameters, string outputDirectory) in DocumentBuilder.cs:124
  at void BuildDocument(BuildJsonConfig config, BuildOptions options, TemplateManager templateManager, string
     baseDirectory, string outputDirectory, string templateDirectory) in DocumentBuilderWrapper.cs:42
  at string Exec(BuildJsonConfig config, BuildOptions options, string configDirectory, string outputDirectory) in
     RunBuild.cs:39
  at void <Execute>b__0() in BuildCommand.cs:19
  at int Run(LogOptions options, Action run) in CommandHelper.cs:44
  at int Execute(CommandContext context, BuildCommandOptions settings) in BuildCommand.cs:15
  at Task<int> Execute(CommandContext context, CommandSettings settings) in CommandOfT.cs:40
  at Task<int> Execute(CommandTree leaf, CommandTree tree, CommandContext context, ITypeResolver resolver,
     IConfiguration configuration) in CommandExecutor.cs:144
  at async Task<int> Execute(IConfiguration configuration, IEnumerable<string> args) in CommandExecutor.cs:83
  at async Task<int> RunAsync(IEnumerable<string> args) in CommandApp.cs:84

[jmckenzie-dev]

Ran into the same problem here. If you nuke the toc.html.tmpl and toc.tmpl.partial files it'll build but you won't have a toc or searchable filter on the table of contents page or class click-through pages.

This is using the latest release from https://github.com/dotnet/docfx on Windows 11.

[neilpendlington]

Interesting. Just looking and the last commits for those files were years ago so I wonder if it's a breaking change or bug in docfx then. I'm brand new to docfx, so I'll have to invest a bit of time into debugging it at some point.

[neilpendlington]

@jmckenzie-dev If you rename toc.html.tmpl in the root of the template folder to toc.html.primary.tmpl, then the build works - although it looks like this was probably based off a different "modern" template because some of the UI is a bit ugly and probably needs some re-work.
Since the docfx documentation on the templating system is fairly light on detail, I can't decide if this is a "by design" or astraight out bug in docfx.

If it's by design, then in the situation where one of the ancestor templates contains primary renderer, that the leaf template needs to deliberately override that primary explicitly. Then the error handling needs to be improved in docfx to show a sensible error, and the discordfx template needs a rework).

Or, docfx should consider the template's renderers in "random order" as per the documentation, but still allow any non-primary renderer in the leaf node template to override an ancestor template's primary renderer.

[lucasteles]

same problemn, any workaround?