dotnet / dotnet/docfx

[Feature Request] Custom TemplateRenderer support

Open
#9,192 1 comment 0 reactions 0 assignees View on GitHub
static-site
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

**Is your feature request related to a problem? Please describe.**

I want to create custom docfx theme by using Razor C# template.
Because current Mustache based-template has limited features and hard to maintenance.

On docfx v3. There is a plan to support **Razor-based** template system.
https://github.com/dotnet/docfx/blob/v3/docs/designs/overview.md#razor-template-engine

And it seems some functionalities are already implemented to provide landing pages.
https://github.com/dotnet/docfx/tree/v3/src/Microsoft.Docs.Build.Specialized/template

**Describe the solution you'd like**
Support `ITemplateRenderer` based custom renderer for **`Docfx.App` user**.

For docfx.exe user.
It might needs to support following features at first.

https://github.com/dotnet/docfx/issues/9058#issuecomment-1671314416
> Eventually I think we would publish templates separately from the executable, for both the official templates and community templates.
> Packaging options are open for discussion, such as NuGet (https://github.com/dotnet/docfx/issues/7974), npmjs, git, OCI, etc.

**Implementation consideration**

Current TemplateManager related class assuming Mustache(or ~~Liquid~~) based template files.
So it require some code modification.

As a minimum solution. I'm considering following code changes on local.
1. When custom plugin is loaded. It register `ITemplateRenderer` with supported document type. (e,g, Conceptual/LandingPage)
2. When processing model's with `TemplateModelTransformer`. Dynamically switch renderer based on document type.

If there are clearer way to support custom template renderer., Please let me know.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.