Vsxmd 1.4.3-beta.2

This is a prerelease version of Vsxmd.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Vsxmd --version 1.4.3-beta.2
NuGet\Install-Package Vsxmd -Version 1.4.3-beta.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Vsxmd" Version="1.4.3-beta.2">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Vsxmd --version 1.4.3-beta.2
#r "nuget: Vsxmd, 1.4.3-beta.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Vsxmd as a Cake Addin
#addin nuget:?package=Vsxmd&version=1.4.3-beta.2&prerelease

// Install Vsxmd as a Cake Tool
#tool nuget:?package=Vsxmd&version=1.4.3-beta.2&prerelease

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

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.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Vsxmd:

Package Downloads
SlackWebhook

Client used to build and send Slack messages to a channel, using a slack incoming webhook which can easily configured

SweetLib

Sweet collection of helpful utils in .Net

SweetLib.IO

SweetLib IO package

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on Vsxmd:

Repository Stars
microsoft/AdaptiveCards
A new way for developers to exchange card content in a common and consistent way.
loklak/loklak_dotnet_api
A C#.NET Wrapper for Loklak to be used with Windows applications
Tewr/BlazorFileReader
Library for creating read-only file streams from file input elements or drop targets in Blazor.
roger-castaldo/BPMNEngine
A BPMN Engine written in .net
Version Downloads Last updated
1.4.5 267,828 2/24/2020
1.4.5-beta.1 539 2/22/2020
1.4.4 24,623 2/14/2020
1.4.3-beta.2 709 1/24/2020
1.4.2 20,413 4/29/2019
1.4.1 29,543 1/26/2019
1.3.3 33,745 8/18/2018
1.3.1 3,230 7/27/2018
1.3.0 1,139 7/26/2018
1.2.0 17,764 1/22/2016
1.1.0 1,430 9/30/2015
1.0.1 1,079 9/29/2015
1.0.0 1,165 8/19/2015
0.2.2 1,317 8/19/2015
0.2.1 1,269 8/17/2015
0.2.0 1,306 8/17/2015
0.1.0 1,531 8/16/2015