Docfx v3 Open Source Release Prototype

[yufeih]

Track the progress of docfx v3 open-source release prototype. The prototype is intended to include these essential functionalities to build a static .NET API reference website:

• Content authoring: Add articles, table of contents, landing pages using markdown or YAML files.
• .NET API reference: Generate .NET API reference pages from DLLs and XML documentation files using a fork of mono/api-doc-tools. Build from csproj files will not be part of this prototype.
• Site template customization: Allow customization of the default site template, using modern website development tools.
• Publish to static hosting sites: Produces static HTML files to be published to static hosting sites like GitHub Pages or Azure Blob Storage

Dogfood

Run the prototype against these Open Source .NET Foundation Projects, finding bugs and feature gaps:

• BenchmarkDotnet: https://benchmarkdotnet.org/
• ImageSharp: https://docs.sixlabors.com/
• Azure SDK for .NET: https://azure.github.io/azure-sdk-for-net/

.NET API Reference Pipeline

• docfx build triggers .NET API reference pipeline
• Building .NET API docs without defining monikers
• Ignore DLL dependency resolve failure
• Resolve BCL types using official xrefmap files generated from https://github.com/dotnet/dotnet-api-docs
• Fix API reference page element styles

Site Template Customization

• Update to bootstrap 5
• Allow basic site customization without forking this template repo
• Home page
• Hub page
• Finalize page visual
• Adjust page visual on mobile devices

Misc

• HTML -> PDF using headless chrome

Additional Features

Additional features that are not part of this prototype but should be considered at a later stage:

• PDF
• Site search
• Sitemap
• Versioning
• API doc files outside of source code
• docfx serve watch content changes

[DavidMarquezF]

First of all, thank you a ton for the work being done here, this is looking very promising

I have a few suggestions for this point:

Allow basic site customization without forking this template repo

• Links in footer
• Be able to create your own Quote templates. I know now there is NOTE, WARNING, etc. It would be interesting to see if we could provide you with a yml where you could specify a list of: icon, identifier, title and color. This way we could add as many as we wanted
• It would be very useful if you could disable contribution links. A lot of projects just need to show the documentation without letting the community modify it. This means things like the github star, the Edit content button, etc.

[DavidMarquezF]

I also think I found an issue with the header links:

For the toc links you take into consideration if it is a relative or absolute path. However, it seems like you cannot make absolute paths work in the menu.yml (it doesn't matter if it comes from xref or if it's hardcoded there).

In the toc:

template/src/scripts/toc.tsx

Line 37 in eb44c92

node.href = isRelativePath(node.href) ? tocrel + '/' + node.href : node.href

In the nav:

template/src/scripts/nav.tsx

Line 27 in eb44c92

const href = navrel + '/' + item.href

[yufeih]

Thanks @DavidMarquezF. These are all valuable feedbacks!

Be able to create your own Quote templates. I know now there is NOTE, WARNING, etc. It would be interesting to see if we could provide you with a yml where you could specify a list of: icon, identifier, title and color. This way we could add as many as we wanted

I'm thinking about exposing these knobs using CSS variables, which could support a wide range of site visual configurations. It is good know that people wants to customize these tiny details like the warning icon.

[DavidMarquezF]

Good idea, I guess CSS variables would allow to customize everything.

Regarding the relative path issue i pointed out, do you want me to create a separate issue for it / create a pull request?

[yufeih]

A pull request would be great!

[DavidMarquezF]

However, I was thinking not only about being able to style the existing Quote Notes.

This is not related to this repository, but since you're involved in both and it also affects the template I'll post this here in order to discuss even if its something in scope. The main problem I see is that the QuoteSectionNote extension is hardcoded:

private readonly List<string> _noteTypes = new() { "[!NOTE]", "[!TIP]", "[!WARNING]", "[!IMPORTANT]", "[!CAUTION]" };

It would be nice if the template itself provided these through the context. Then all the templates (no only this one) would have full control over these properties. Maybe adding in the context a variable to specify this list and then take it from there.

Also, it would be nice that they could be translated to other languages. Looking at the docfx source it looks like this should be added inside ContentTemplate/token.. Is this something the template is going to provide or the users should do it?

[yufeih]

However, I was thinking not only about being able to style the existing Quote Notes.

This is not related to this repository, but since you're involved in both and it also affects the template I'll post this here in order to discuss even if its something in scope. The main problem I see is that the QuoteSectionNote extension is hardcoded:

private readonly List<string> _noteTypes = new() { "[!NOTE]", "[!TIP]", "[!WARNING]", "[!IMPORTANT]", "[!CAUTION]" };

It would be nice if the template itself provided these through the context. Then all the templates (no only this one) would have full control over these properties. Maybe adding in the context a variable to specify this list and then take it from there.

Also, it would be nice that they could be translated to other languages. Looking at the docfx source it looks like this should be added inside ContentTemplate/token.. Is this something the template is going to provide or the users should do it?

This one needs an issue in https://github.com/dotnet/docfx. It is more than just a template change.

[DavidMarquezF]

Will do :)

[JM2K69]

Why do you remove HUB page from TODOList ?