Docfx: 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.

[superyyrrzz]

Hinted by #1253 , we can add a post step (Maybe a PostProcessor) to convert HTML pages to Markdown files.

[open-collar]

This would be really useful as a means of posting generated documentation in Azure DevOps (as a "Code Wiki"). For that reason I would support the standards recommended by them here which includes the standard DaringFireball standard and the GitHub Extensions.

[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.