Support output as Markdown instead of html, for example, for github readme.md

[MathewSachin]

DocFX does a great job in building static websites.
But, I want to know if there is a way to export the files in Markdown.
It would then be easy to put up on GitHub wikis or GitBook.

And by that I mean that I don't require features like search, Affix, Breadcrumb, navbar, footer, etc.

Here's what I tried:

• Renamed *.html.primary.* files to *.md.primary.*
• Modified partials and templates from html to markdown.
• Removed unnecessary features.

That was a good progress but with two major problems:

1. Markdown in conceptual documentation was getting converted to html. I really need to prevent this. Trying to add the *.md files to resources failed resulting in unresolved links.
2. Xml Documentation was being converted to html.

So, finally it seems that I want some way to convert that output html to markdown.

Any help is appreciated and BTW thank you for this awesome software.

[chenkennt]

@MathewSachin if you don't want markdown to be converted to html, what kind of functionality do you want from DocFX? You can directly send your markdown files to gitbook..

[MathewSachin]

@chenkennt I want DocFX to extract xml documentation from source code and augment my markdown files into it.

[vwxyzh]

@MathewSachin if you don't need merge overwrite document for managed reference, I think you can do it by following steps:

1. Create your custom document processor:
   • Inherited from ManagedReferenceDocumentProcessor
   • Override steps property different contract name (disable mark to html).
   • Give higher priority (disable default ManagedReferenceDocumentProcessor),
2. Create your custom template to create markdown file.

[MathewSachin]

@vwxyzh Merging overwrite documents is necessary for me. But, still your idea seems implementable. I will definitely try this.

[MathewSachin]

Another problem arised that xrefs are not being resolved.

For example, see https://github.com/ManagedBass/ManagedBass.DocFX/tree/gitbook

[vwxyzh]

@MathewSachin Merging overwrite documents is based on html format, it is too hard to implement in markdown format.
And I don't have any idea for xref problem.

[vicancy]

@MathewSachin Your website https://managedbass.github.io/api/ManagedBass.html looks pretty cool, would you willing to share it to http://dotnet.github.io/docfx/templates-and-plugins/templates-dashboard.html ?

[MathewSachin]

I would be happy to have it shared.

But, it is based on a previous version of DocFX.
Some recent changes in DocFX have resulted in some bugs in my website because my template is for the older versions.

The template really needs to be tweaked before sharing.
I will let you know once it is ready

[vicancy]

Different document type are sharing the same layout https://github.com/dotnet/docfx/tree/dev/src/docfx.website.themes/default/layout now, so I assume it is now much easier to change layout? 😄

[MathewSachin]

@vicancy I have created a new repository with the code for my DocFX template: https://github.com/MathewSachin/docfx-tmpl

You can add it to the Templates and Plugins page.
I would try to improve it further.

[Qevlarr]

I also request this feature. Documentation should be easy to find. Github (and other platforms) show a markdown readme right on a project's main page. It would be great if we can refer to generated documentation pages (again in markdown) with something like xref. The platform can style the markdown for me, that's not as important as having all the docs in one easy to find place.

[bloudraak]

I'm also in favor of Markdown... but for different reasons. We often have to incorporate our documentation with other content management systems that support markdown. For example, we need to upload our APIs to Confluence, WordPress or some other system that supports Markdown. The markdown has to be simple, limited to something like CommonMark, with simple code blocks, headings. Some of these CMS tools prefer the file structure to be in a single directory (e.g. Confluence doesn't support subdirectories when linking between pages) and pages needs to be unique. For API pages, the TOC on the left side is better served as its own page; each namespace and/or assembly may need its own page too. The class reference page can then link the namespace/assembly.

It is ok to lose some features provided by the HTML output of DocFX, e.g. searching, styling etc, since that will all be taken care of by the CMS.

[CaptainCanonical]

I seem to be going in circles trying to find the answer to how to make docfx generate output in markdown instead of html. Is the answer what @vwxyzh posted on Sep 9, 2016 about creating your own custom processor, etc? Is there no simpler solution yet?

[longbombus]

It would be great if it will generate wiki pages instead of static site.

[lloydjatkinson]

Is there really no plan for markdown support?

[jsiegmund]

Came here in search for the same, also looking for a way to better integrate documentation we have in our Azure DevOps wiki along with documentation generated by docfx. Markdown output would be a perfect solution for us.

[daniellopezgarcia]

@jsiegmund I came here as well. After digging up a little, I found that .NET already generates structured (in xml format) documentation, which then can be parsed relatively easy into .md files. You just need to enable it from the build options and set the destination file. For my internal needs this may suffice for now but I'm sharing the script in case someone finds it useful. Apologies for the lack of interfacing but this is exactly what I need. Feel free to modify to suit your needs! (Change the input file or make it a input to the script)

Read an input xml which follows this format, extract its classes and interfaces, and for each one, extract its associated methods and properties and print them. Concatenates multiline summaries into a single line, but tries to keep lists as they are intended.

# Using .xml files within this same directory, generates .md files containing MS Doc-like style documentation
# for classes and methods.

$documentationComments = [xml](Get-Content '.\Namespace.Project.xml')

# Obtain types and then its methods, constructors and constants.
$documentationComments.doc.members.ChildNodes | Where-Object { $_.name.StartsWith("T:")} | ForEach-Object {
    $element = $_
    $fullyQualifiedName = $element.name -replace "^T:",""
    $typeNamespace = $fullyQualifiedName.SubString(0, $fullyQualifiedName.LastIndexOf('.'))
    $typeName = $element.name.Split(".")[-1]
    Write-Host "Processing C# type $($typeName)"
    $mdFileName = "$($typeNamespace).$($typeName).md"
    $typeTrimmedSummary = $element.summary -replace "`n +","`n" -replace "^`n", "" -replace "`n$","" -replace "`n-","`n"

    # Add basic documentation (simple .xml to .md conversion)
    $AutogeneratedMDContent = @"

# $($typeName)

## Definition

*Namespace: $($typeNamespace)*

*Assembly: $($documentationComments.doc.assembly.name).dll*

$($typeTrimmedSummary)
"@

    # Add properties documentation
    if(($documentationComments.doc.members.ChildNodes | Where-Object { $_.name -match "^P:$($fullyQualifiedName -replace "\.","\.")\.[_a-zA-Z0-9]+"}).Count -gt 0){
        $AutogeneratedMDContent += "## Properties`n`n|Name|Description|`n|--|--|"
    }
    $documentationComments.doc.members.ChildNodes | Where-Object { $_.name -match "^P:$($fullyQualifiedName -replace "\.","\.")"} | ForEach-Object {        
        $propertyInfo = $_
        $propertyFullyQualifiedName = $propertyInfo.name -replace "^P:",""
        $propertyName = $propertyFullyQualifiedName.Split(".")[-1]
        Write-Host "Property $($propertyName) belongs to $($typeName)"
        $propertyTrimmedSummary = $propertyInfo.summary -replace "`n +","`n" -replace "^`n", "" -replace "`n$","" -replace "`n"," "
        $AutogeneratedMDContent += "`n|$($propertyName)|$($propertyTrimmedSummary)|"
    }

    # Add methods documentation
    if(($documentationComments.doc.members.ChildNodes | Where-Object { $_.name -match "^M:$($fullyQualifiedName -replace "\.","\.")\.[_a-zA-Z0-9]+\("}).Count -gt 0){
        $AutogeneratedMDContent += "## Methods`n`n|Name|Description|`n|--|--|"
    }
    $documentationComments.doc.members.ChildNodes | Where-Object { $_.name -match "^M:$($fullyQualifiedName -replace "\.","\.")\.[_a-zA-Z0-9]+\("} | ForEach-Object {
        $methodInfo = $_
        $methodFullyQualifiedName = $methodInfo.name -replace "^M:",""
        $methodSignature = $methodFullyQualifiedName -replace "^([0-9a-zA-Z]+\.)+","" -replace "System.String,","string, " -replace "System.String\)", "string)"
        Write-Host "Method $($_.name) belongs to $($typeName)"
        $MethodTrimmedSummary = $methodInfo.summary -replace "`n +","`n" -replace "^`n", "" -replace "`n$","" -replace "`n"," "
        $AutogeneratedMDContent += "`n|$($methodSignature)|$($MethodTrimmedSummary)|"
    }

    $AutogeneratedMDContent | Out-File $mdFileName
}

The good news is that extracting formatted comments into an structure is already done by .NET, not DocFX. The other good news is that converting from structured to simple .md is almost as straightforward as above (depends on what you need). Bad news is that its not done!

[yufeih]

https://github.com/ap0llo/mddocs seems like a promising tool to produce .NET API reference documentation in markdown format.

[daniellopezgarcia]

https://github.com/ap0llo/mddocs seems like a promising tool to produce .NET API reference documentation in markdown format.

Seems very promising!
A little context is that we have docfx taking a wiki-like, git repository into producing nice html output. However, its a large, common wiki hosting multiple team's own style of documentation according to their needs, so it meets some flexibility for each team. However, its inputs are .md files, so that we do currently .cs -> .xml (by .NET) -> .md (by above script/promisind mddocs) -> .html (by docfx). This means no actual source code .cs is available for docfx when building this wiki into a nice html page.

I'm going to check whether just adding the .xml into the wiki repo gets docfx to generate .html documentation. The end goal is to have whatever format is required by our documentation process needs, I can think that for some people it can even mean PDF, but if .xml -> .html is directly possible (skipping .md altogether), then that also works just fine!

[Muchaszewski]

https://github.com/ap0llo/mddocs seems like a promising tool to produce .NET API reference documentation in markdown format.

Unfortunately, mddocs will not work as it requires full to provide all assemblies and XML file generated. It also doesn't support tags like see, inheritdoc and exceptions.

I would love to see fully supported MarkDown files generated from docfx as it has the most mature engine to take all the metadata.

[Ole-Visma]

More than 6 years since this "must have" feature without any solution...

[akovanev]

I've just created a small package which may slightly help with the issue (at least it helped for our project). I'll put it here if you don't mind.

However, it would be really nice to get a simple api retrieving the documentation data as a part of docfx.

[MPeli]

@yufeih, I see that you added this issue to Working Set. Does it mean that this feature request is currently being worked on? Thank you.

[yufeih]

Yes! I should have some initial PR ready this week.

[MPeli]

@yufeih, thank you so much! We are really looking forward to using this new feature. Let me know if you need any help with testing.

[yufeih]

Experimental support of markdown output is added to 2.71.0 using the outputFormat: markdown config:

{
  "metadata": [
    {
      "outputFormat": "markdown",
    }
  ],
}