mdG

This is a fork of the Vsxmd project described below. The MIT license is preserved for all changes and additions introduced in this fork. The features supported are almost identical, except:

• Markdown is now output into separate folders on a namespace, class and member type basis.
• Each method, property, class, field and constructor outputs to a separate markdown file.
• Return types of methods are determined by looking for a "see" tag in the "returns" tag.
• Type (class) Markdown files contain a summary of all type members in a table.
• References to members are now resolved by relative links between folders/files.
• Namespace/Assembly are included on all member's markdown files.
• System namespace references now use docs.microsoft links instead of msdn links.

The intention of these changes was to mimic the format used by docs.microsoft, where each class has its own folder, with a page for constructors, and a folder for all methods, fields and properties, referred to by the main class page via a summary table.

Since the XML generated by VS does not provide information regarding the return type of a method, you should specify the return type to be displayed in the markdown by using a "see" tag in the "returns" tag". For example:

<returns><see cref="System.String"/></returns>

Known issues (on roadmap)

• Constructors page only returns one constructor.
• Unable to properly view Generic types i.e. List
• Inheritdoc not applying markdown from base class.

To be Added

• Non-spec elements (Implements, Inherits, PropertyValue etc.)
• Potentially expand the IntelliSense available option for VS.

Extension

Currently in the process of turning this into a VS extension. So far this project creates an MSI that can be used to install an extension. Due to my lack of experience in this area, the installer will copy the main Vsxmd exe to program files to be called during post-build, while installing an extension via VSIX that allows the user to configure how Markdown will be output during post-build. Building the installer requires the Installer extension on VS (available for free), while the extension component requires the VSSDK utilities, available in the VS installer.

In the future, I will include an MSI in the repo so you won't need these utilities to build for yourself. As it stands, the MSI portion can be circumvented by:

• Copying Vsxmd.exe to a folder on your machine.
• Adding this path to the "PATH" environment variable in Windows.

This allows the post-build step to run the executable without having to know where it is installed, which is a limiting factor of MSBuild / proj files.

The VSIX component must still be built. This is simply a wrapper to allow the user to right-click on a project and "Configure Markdown..." and select an output directory. This manually updates the csproj or vbproj file to include a post-build target that outputs markdown to the specified directory. You can also implement this for yourself with the following Target element (place anywhere inside the document root node (project):

<Target Name="mdGTask" AfterTargets="PostBuildEvent">
    <PropertyGroup>
        <mDOutput>{relative/File/Path/Here/}</mDOutput>
        <mdGExecute>Vsxmd "$(DocumentationFile)" "$(mDOutput)"</mdGExecute>
    </PropertyGroup>
    <Exec Command="$(mdGExecute)"/>
</Target>

Where the mDOutput tag uses forward-slashes for directory separators and a trailing slash. You should also configure the XML Documentation path in the conventional way, via Properties -> Build.

Vsxmd

A MSBuild task to convert XML documentation to Markdown syntax. Support both .Net Framework and .Net Core projects.

Features

• Provide full information from the XML documentation file.
• Provide easy reading facilities - parameter table, link tooltip, etc.
• Provide table of contents to type and member links.
• Highlight code block through <code lang="csharp"> tag.
• Reference System types to official MSDN pages.

Get Started

If you are using Visual Studio:

• In Visual Studio, right click project name to open project properties window.
• Switch to Build tab, in Output section, check XML documentation file checkbox.
• Install Vsxmd package from NuGet.
• Build the project, then a markdown file is generated next to the XML documentation file.

If you are using .Net Core CLI:

• Open project's CSPROJ file, declare DocumentationFile property in PropertyGroup section. The path is relative to the project directory. MSBuild Reserved and Well-Known properties are also available for this property.
• Run dotnet add package Vsxmd to install the the package to the project.
• Run dotnet build to build the project and generate the XML documentation and Markdown files.

Vsxmd Options

There are some properties to customize the Markdown file generation process. They are all optional. If you want to use them, declare them in CSPROJ file's PropertyGroup section.

DocumentationMarkdown

It is used to specify the generated Markdown file path. It defaults to the XML documentation file name with .md extension, under the same folder as the XML file. Similar to DocumentationFile property, the path is relative to the project directory and MSBuild properties are available.

Example

<PropertyGroup>
    <DocumentationMarkdown>$(MSBuildProjectDirectory)\API.md</DocumentationMarkdown>
</PropertyGroup>

VsxmdAutoDeleteXml

A boolean flag to delete the XML documentation file after the Markdown file is generated.

Example

<PropertyGroup>
    <VsxmdAutoDeleteXml>True</VsxmdAutoDeleteXml>
</PropertyGroup>

Extend XML documentation

There are some extended features based on XML documentation. They are not described in XML recommended tags, but they are worth to use.

Highlight Code Block

To highlight code block in the Markdown file, declare the attribute lang in <code> tag and set it to a program language identifier.

Example

<code lang="javascript">
    function test() {
        console.log("notice the blank line before this function?");
    }
</code>

Programmatic API

This library provides the following programmatic API to convert XML documentation file to Markdown syntax programmatically.

• Converter : IConverter
  • string ToMarkdown()
  • static string ToMarkdown(XDocument document)

Markdown File Demo

The best demo is this project's documentation file, Vsxmd.md. It is generated by this project itself.

Known Issue

The syntax for the list comment tag is not well defined. It will be skipped during render. If you have ideas, please open an issue.

Credits

This project is initially inspired from a gist. But in the later releases, the implementation is rewritten.

License

MIT License.