Need help with Vsxmd?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

lijunle
162 Stars 43 Forks MIT License 279 Commits 18 Opened issues

Description

VS XML documentation -> Markdown syntax.

Services available

!
?

Need anything else?

Contributors list

# 78,648
express...
webpack...
c-sharp
web-app...
170 commits
# 23,085
F#
.NET
macOS
linq
3 commits

Vsxmd

AppVeyor NuGet

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

    $(MSBuildProjectDirectory)\API.md

VsxmdAutoDeleteXml

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

Example

    True

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
tag and set it to a program language identifier.

Example


    function test() {
        console.log("notice the blank line before this function?");
    }

Programmatic API

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

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.