This application converts XML documentation files into Markdown format, facilitating documentation generation compatible with MkDocs. MkDocs is a static site generator optimized for creating project documentation from Markdown files, configured via a YAML file. The tool supports a range of customization options for processing XML documentation, including file and namespace exclusion, output formatting, and handling of unsupported XML tags.
For comprehensive guidance on leveraging MkDocs with the generated markdown, see MkDocs website.
Review the Options class for an enumeration of configurable parameters impacting conversion behavior.
See supported XML documentation tags see here.
To add a description of the assembly, add a summary tag to a AssemblyDoc class.
There is also a settings.json Example to filter out Files and Namespaces
Notice: As this tool uses Reflection to add additional information to the XML documentation, the DLL´s of the project must be in the same directory as the XML documentation files.
The following examples demonstrate various ways to use the XmlDocToMd tool to convert XML documentation to Markdown format, showcasing the flexibility and range of options available: Basic conversion of a single XML file to Markdown:
XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\output.md"Convert all XML documentation files in a specific directory to Markdown, outputting to a designated directory. This example uses the search directory and directory name options to filter XML files located in a 'Release' subdirectory:
XmlDocToMd.exe -s "C:\Project\Docs" -d "Release" -o "C:\Project\MarkdownDocs"Use a secondary output directory for additional file handling, such as backup or versioning, demonstrating the tool's support for complex documentation workflows:
XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\Markdown\output.md" -l "C:\Backup\Docs"Handle unexpected XML tags by issuing a warning, allowing for the identification and resolution of issues in the source XML without halting the conversion process:
XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\output.md" -u WarnConvert XML documentation to Markdown using Git Markdown format for URLs, which is useful when the generated Markdown will be hosted on GitHub or a similar platform:
XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\README.md" -gName the output Markdown file "README.md" instead of using the assembly name, making it ready for use as a GitHub repository's landing page documentation:
XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\output.md" -rVisual Studio post-build event example to convert XML documentation to Markdown when building a project with custom configuration:
<Target Name = "PostBuild" AfterTargets="PostBuildEvent" Condition="'$(ConfigurationName)' == 'XMLtoMD'">
<Exec Command = "call "$(TargetDir)$(TargetName).exe" -s "$(ProjectDir)\" -d "$(ConfigurationName)" -o "$(ProjectDir)\" -g -r" />
</Target>These examples illustrate just a few of the ways the XmlDocToMd tool can be configured to meet specific documentation conversion needs, from simple file conversions to more complex scenarios involving multiple directories, console integration, and special formatting requirements.
Common Tags:
doc: The root tag for the documentation file. It's not used within code comments but in the generated XML file.summary: Describes a type, method, property, field, or event.remarks: Provides additional information about a type or member, often used to explain the behavior not covered in thesummary.example: Gives an example of how to use a method, class, or other member.code: Encloses example code. Thelangattribute can specify the language of the code snippet (e.g., lang="C#").param name="name": Describes one of the parameters for a method. Replacenamewith the name of the parameter.typeparam name="name": Describes the type parameter for a generic type or method. Replacenamewith the name of the type parameter.returns: Describes the return value of a method.exception cref="exceptionType": Indicates what exceptions can be thrown by a method. ReplaceexceptionTypewith the type of the exception.see cref=""/>: Creates a hyperlink to the specified member or type. Use thecrefattribute to specify the code element.seealso cref=""/>: Similar tosee, but typically used in the context of a "See Also" section.value: Describes the value of a property.list: Used to format a list of items. Thetypeattribute specifies the list type (e.g., bullet, number, table), and thenameattribute gives a name to the list.item: Defines an item in a list. Often used withinlist.
Formatting Tags:
para: Starts a new paragraph.c: Marks text as code within a description.paramref name="name": References a parameter within a description. Replace the placeholder with the parameter's name.typeparamref name="name": References a type parameter within a description.name: Typically used within other tags to specify names but not a standalone tag in XML documentation comments.description: Not a standard XML documentation tag in C#. Descriptions are typically included within the content of tags likeitem.
HTML-like Tags:
b: Bold text.br: Line break.a href="url": Creates a hyperlink. Replaceurlwith the target URL.h1,h2,h3,h4: Headers of different levels.
Options for customizing the behavior of the XML documentation to Markdown conversion. These options allow for detailed control over input and output paths, handling of console input/output, secondary output directories, unexpected tag management, and more.
| Name | Type | Description |
|---|---|---|
| InputFile | String | Gets or sets the input XML file path. Use -i or --inputfile followed by the file path to specify the input XML file. |
| ConsoleIn | Boolean | Gets or sets a value indicating whether to read input from the console. Use --cin to read input from the console instead of a file. |
| OutputFile | String | Gets or sets the output markdown file path. Use -o or --outputfile followed by the file path to specify the output markdown file. |
| SecondaryOutputDirectory | String | Gets or sets the path to a secondary output directory. To copy to a network share for example. Use -l or --secondaryDir followed by the directory path to specify a secondary output directory. |
| ConsoleOut | Boolean | Gets or sets a value indicating whether to write output to the console. Use --cout to write output to the console instead of a file. |
| UnexpectedTagAction | UnexpectedTagActionEnum | Gets or sets the action to take on unexpected tags. Use -u or --unexpected followed by Accept, Warn, or Error to specify how to handle unexpected tags. |
| SearchDirectory | String | Gets or sets the search directory for XML files. Use -s or --search followed by the directory path to specify where to search for .xml files. This is used in combination with the -d or --directory argument. |
| Directory | String | Gets or sets the directory name to search for .xml files. Use -d or --directory followed by the directory name. This is used in combination with the -s or --search argument. Defaults to "Release". |
| Git | Boolean | Gets or sets a value indicating whether to use Git Markdown format for URLs. Use -g or --git to use Git Markdown format. |
| Readme | Boolean | Call the Markdown file "README.md" instead of AssemblyName.md Use -r or --readme to call the Markdown file "README.md" instead of AssemblyName.md |
| SettingsFile | String | Gets or sets the settings file. Defaults to "settings.json". Use -f or --settings followed by the file path to specify the settings file to use. |
Json Settings file for the XmlDocToMd
| Name | Type | Description |
|---|---|---|
| FilesToIgnore | List‹String› | Wich xml files to ignore when converting to markdown |
| NameSpacesToRemove | List‹String› | Wich namespaces to ignore when converting to markdown |
Specifies the manner in which unexpected tags will be handled
| Name | Type | Description |
|---|---|---|
| Error | UnexpectedTagActionEnum | No unexpected tags are allowed |
| Warn | UnexpectedTagActionEnum | Warn on unexpected tags |
| Accept | UnexpectedTagActionEnum | All unexpected tags are allowed |
Generated by XmlDocToMd by ROBdk97