Generate Markdown From Your Nuget Package

• Download the source code and view my example

Install app runtime for this utility tool:

• PM> Install-Package VB_AppFramework

Load nuget describe metadata

Parsing nuget package description meta data file by using XML deserialization:

There are two sections in the nuget package meta data:

• metadata

The metadata section records the summary information about your nuget package, and it can be parsing by just using a simple class:

Public Class metadata

    <XmlAttribute> 
    Public Property minClientVersion As String
    Public Property id As String
    Public Property version As String
    Public Property title As String
    Public Property authors As String
    Public Property owners As String
    Public Property licenseUrl As String
    Public Property projectUrl As String
    Public Property requireLicenseAcceptance As Boolean
    Public Property description As String
    Public Property summary As String
    Public Property releaseNotes As String
    Public Property copyright As String
    Public Property language As String
    Public Property tags As String
    Public Property frameworkAssemblies As frameworkAssembly()
End Class

Public Class frameworkAssembly
    <XmlAttribute> Public Property assemblyName As String
    <XmlAttribute> Public Property targetFramework As String
End Class

• files

The file list item mainly consists of two attributes:

Public Class file
    <XmlAttribute> Public Property src As String
    <XmlAttribute> Public Property target As String
End Class

So that finally, we can build a simple class object for stands for the description meta data:

<XmlRoot("package", [Namespace]:="http://schemas.microsoft.com/packaging/2013/01/nuspec.xsd")>
Public Class Nuspec

    Public Property metadata As metadata
    Public Property files As file()

End Class

The by construct this meta data class object, and this will make the parsing of nuget package metadata easily in one line of code:

Dim nuspec As Nuspec = path.LoadXml(Of Nuspec)

Output Markdown Document From Meta

Learn the markdown syntax can be reviewed from Mastering Markdown, and this section about how to generate some link element from the nuget.

The Nuget Tag Link

The tag links on the nuget is in the format as https://www.nuget.org/packages?q=Tags%3A"{tag_data}"

Imports System.Xml.Serialization
Imports Microsoft.VisualBasic.ComponentModel.DataSourceModel
Imports Microsoft.VisualBasic.Language
Imports Microsoft.VisualBasic.Linq

The tags data in the nuget package description meta data consists of several tag tokens and each token is separated by a space, so that we can parse the tag data just by using String.Split function, and then generate the tag and link data by using string interpolating or String.Format function. Here is the example:

Public Function GetTagLinks() As NamedValue(Of String)()
    If String.IsNullOrEmpty(tags) Then
        Return {}
    End If

    Dim tokens As String() = tags.Split
    Return tokens.ToArray(Function(tag) New NamedValue(Of String)(tag, _
	$"https://www.nuget.org/packages?q=Tags%3A""{tag}"""))
End Function

Public Function TagsMarkdownLinks() As String
    Dim LQuery As String() =
        LinqAPI.Exec(Of String) <= From tag As NamedValue(Of String)
                                   In GetTagLinks()
                                   Select $"[{tag.Name}]({tag.x})"
    Return String.Join(" ", LQuery)
End Function

Due to the reason of the link syntax in markdown is:

[Caption text](url)

So that we can simply generate the tag link data for markdown by using string interpolating:

VB.NET

$"[{tag.Name}]({tag.x})"

Processing the author links in the nuget is the same as tag data:

https://www.nuget.org/profiles/{nuspec.metadata.authors}"

The whole function for generating the markdown document is in this file: MarkdownGenerator.vb

Now we can generate the markdown document for your nuget package:

Public Function ExecFile(path As String, args As CommandLine) As Integer
    Dim nuspec As Nuspec = path.LoadXml(Of Nuspec)
    Dim md As String = nuspec.Document
    Dim out As String = path.TrimFileExt & ".md"
    Return md.SaveTo(out).CLICode
End Function

Load your nuget metadata as XML, and then generate the markdown, then last save the document string.