Generating plain Markdown files that look as close to the Microsoft documentation pages as possible.

[just-ero]

Hi.

Docfx is great. But for my purposes, it's way over-complicated. I don't need to host any page, a set of plain Markdown files containing the information is enough. I am looking for something like what I've created (by hand) here.

Is it possible to have Docfx do this? Would it be possible for me to isolate the parts that output all the symbols and information and do the formatting from there? I've been meaning to create a dotnet tool that does exactly this; generate just Markdown documentation files from solutions, projects, source files, or assemblies. I would like to provide several different formatters as well. GitHub-flavored Markdown doesn't support all the things necessary to format tables the way I want, for example. GitHub Wiki pages need to link to one another differently and I would like to generate a sidebar for them.

Any suggestions for this?

[filzrev]

generate just Markdown documentation files from solutions, projects, source files, or assemblies.

docfx supports markdown output format options.
When this output format is specified. docfx metadata command output plain markdown files.

[just-ero]

This does help already, thanks.

However, the contents of the files are still very malformatted compared to what I would like (as mentioned, as close to the Microsoft documentation pages as possible). You can compare the generated file for the Module class to the one I made by hand. I'll concede I am missing some things (inherited members, extension methods).

But some parts of the generated content is different for no apparent reason:

• the arrow for inheritance (←) is the other way around,
• primitive type names aren't converted to their real names (expect nuint -> UIntPtr),
• inherited members and extension methods are comma-separated, making them very difficult to read,
• the symbol name and kind are backwards (Class Module instead of Module Class).

Some parts appear to be plain broken:

• <see cref="..."/> tags are entirely ignored it seems, leading to incorrect grammar.

And, in my opinion, the generated files are very difficult to read and navigate:

• the files do not have any kind of hierarchy (directories for the namespaces would be nice at least),
• the files contain all of their members and their information back to back, making it hard to spot anything substantial at a glance (distinguishing between an H3 and an H4 is already hard enough); I would love for them to be generated in such a way that a type only contains a table of contained members (split into fields, properties, methods, constructors, etc.) and for those members to have their own file, leading to a very easy-to-navigate file tree.

Here's an example of what I was hoping the file structure to be like:

---

Is there anything at all I can do to have it generated my way?

[filzrev]

markdown output format support are recently added. (#684)
So there may be missing features for some use cases.

---

the arrow for inheritance (←) is the other way around,

It seems modern templates and markdown/apiPage output use UML style inheritance arrow direction.
When using default template. It use learn.microsoft.com compatible inheritance arrows.

I don't know why these style are changed at modern template.
I'll create separate Q&A discussion(#9718).

primitive type names aren't converted to their real names (expect nuint -> UIntPtr),

docfx resolve symbol name to language dependent display name by using Roslyn API (SymbolDisplay.ToDisplayParts).
Currently there is no options available to change this behaviors.

inherited members and extension methods are comma-separated, making them very difficult to read,

Currently API Page-based pages don't support template customization.
It's required to modify ApiPageMarkdownTemplate.cs markdown generator. or adding new output format.

the symbol name and kind are backwards (Class Module instead of Module Class).

As you say, page title (<h1>) name don't seem to be compatible with learn.microsoft.com API reference page.
I don't know there is historical reasons of these or not.

tags are entirely ignored it seems, leading to incorrect grammar.

it seems cref tag is rendered as <xref href="Example2.Module" data-throw-if-not-resolved="false"></xref>.
It might needs custom post processing steps to resolve outputted xrefs inside markdown files.

And, in my opinion, the generated files are very difficult to read and navigate:
the files do not have any kind of hierarchy (directories for the namespaces would be nice at least),

It can split files by specifying "memberlayout": "sepatedPages" option.
To grouping markdown files by directory.
It need to additional option something like separatedDirectoryPages.

[just-ero]

Thanks for the info here. Separating the files helps a lot with readability. It's still a bummer that the members aren't listed in a proper (header-less) table like they are on learn.microsoft.com though.

There are some more issues I've found:

• the markdown files' headers include (what I believe to be) an attempt at an anchor (# <a id="AslHelp_Memory_Module"></a> Class Module); this does not work and instead makes the actual anchor to said header malformatted (#-class-module instead of just #class-module); an actual markdown anchor looks like this: [Class Module](#AslHelp_Memory_Module) (edit: seems like this is already reported at [Feature Request] Make <a/> tag in headers optional when outputFormat: markdown #9720),
• enum values are ordered alphabetically instead of in the order they were declared or the order of their numeric value (this is likely due to the fact that enum values are treated as fields, which are always ordered alphabetically),
• types under Property Value or Returns have a leading space; not an issue, just something I noticed,
• DocFX is incapable of generating documentation for classes in the root namespace (as in, no namespace was provided),
• I believe DocFX may be broken for record struct types, unless I'm incorrect:
  • it generates { get; init; } accessors for record types' properties,
  • it generates { get; init; } accessors for readonly record struct types' properties,
  • but it generates { readonly get; set; } for record struct types' properties; I don't believe set is correct here,
• this[T] indexers have their pages generated with the header Property this, which is misleading; the learn.microsoft.com pages use Item[T] Property as the header.

Like you mentioned, cref gets generated as xref, which cannot be displayed at least by GitHub-flavored markdown.
I haven't found a way to generate files in separate directories.

It would be nice if generated files contained a link to the original source file, ideally including a direct link to the line of the declaration (to the field, property, method, constructor, etc.).

You mention "adding a new output format". How do I do that?

[yufeih]

I would like to provide several different formatters as well

@just-ero

If the outputFormat is apiPage, the output will be some YAML files confirming to this schema. You may be able to build a "custom formatter" that renders it into the desired format you like to some extend. In fact that is how the markdown output format works internally by docfx and here is the code for it to implement.

[just-ero]

Hi, thank you for this information.

This probably allows me to create my own formatter fairly easily (I hope at least, the code is still a bit confusing to me). Seeing as how DocFX is available as a NuGet, I can simply create a console application which does the formatting and outputting, right?

---

Edit:

It appears that the public-facing API for this in DocFX is very frustrating. Even just DotnetApiCatalog's GenerateManagedReferenceYamlFiles is annoying to work with, as it expects a file path and cannot take in a raw json string (side-note: why does this project use NewtonSoft.Json instead of .NET's very own System.Text.Json?), such that I need to figure out a way to feed in a docfx.json file regardless of where my app was executed from.

I will mark your reply as the answer, but please know that working with DocFX in code is near-impossible. It's difficult to understand the lack of an interface that a user can simply implement which can contain their formatting implementation.

[yufeih]

why does this project use NewtonSoft.Json instead of .NET's very own System.Text.Json?
This project was matured way back before System.Text.Json exist - migration is possible but require non-trivial effort.

[poa00]

Docfx is great. But for my purposes, it's way over-complicated. I don't need to host any page, a set of plain Markdown files containing the information is enough. I am looking for something like...

Hi @just-ero, did you ever find a (semi) simple solution to this? I'm looking for exactly the same! Thanks 😃

[just-ero]

As mentioned in the other answer, there is an output format named markdown that you can use. I'm personally not happy with its output and I have not been able to generate what I desire.