{"id":22069691,"url":"https://github.com/robdk97/xmldoctomd","last_synced_at":"2026-05-13T07:09:35.467Z","repository":{"id":222907262,"uuid":"758548829","full_name":"ROBdk97/XmlDocToMd","owner":"ROBdk97","description":"This application converts XML documentation files into Markdown.","archived":false,"fork":false,"pushed_at":"2024-05-24T06:19:23.000Z","size":82,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-29T00:51:42.563Z","etag":null,"topics":["charp","converter","documentation","documentation-generator","markdown","xml"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ROBdk97.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-16T15:02:02.000Z","updated_at":"2024-05-24T06:19:27.000Z","dependencies_parsed_at":"2024-02-16T23:24:51.774Z","dependency_job_id":"a559e7e3-05d2-4d14-a954-a65f57a86692","html_url":"https://github.com/ROBdk97/XmlDocToMd","commit_stats":null,"previous_names":["robdk97/xmldoctomd"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROBdk97%2FXmlDocToMd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROBdk97%2FXmlDocToMd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROBdk97%2FXmlDocToMd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROBdk97%2FXmlDocToMd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ROBdk97","download_url":"https://codeload.github.com/ROBdk97/XmlDocToMd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245152908,"owners_count":20569399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charp","converter","documentation","documentation-generator","markdown","xml"],"created_at":"2024-11-30T20:11:52.632Z","updated_at":"2026-05-13T07:09:35.459Z","avatar_url":"https://github.com/ROBdk97.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XmlDocToMd\nConverts XML documentation files into GitHub-Flavored Markdown, producing output compatible with [MkDocs](https://www.mkdocs.org/) and GitHub Pages.\n\nThe tool reads the standard `.xml` file emitted by the C# compiler alongside the compiled assembly, enriches member signatures via Reflection, and writes a structured `.md` file.\n\nSee the [Options](#robdk97xmldoctomdclioptions) class for every available command-line parameter, and the *Supported XML Documentation Tags* section in [AssemblyDoc](AssemblyDoc.cs) remarks for the full list of handled tags.\n\nUse FilesToIgnore to skip files during batch conversion. The wildcard `*` is supported, for example `System*`, `Microsoft*`.\n\nThe tool looks for an empty public class named [AssemblyDoc](AssemblyDoc.cs) (abstract is recommended) and places its XML documentation at the top of the generated Markdown file. This is used to create a general documentation overview with references to the most important parts and a high-level description, similar to the main section of a README.\n\n\u003e [!NOTE]\n\u003e Because the tool uses [ReflectionHelper](Conversion/ReflectionHelper.cs) to resolve member types and visibility, the compiled `.dll` must reside in the same directory as the `.xml` file. Conversion still succeeds without the DLL, but type information in tables will be reduced to the raw prefix letter (`F`, `P`, …).\n\n**Example**\n\n#### Basic single-file conversion\n\n```bat\n    XmlDocToMd.exe -i \"C:\\Docs\\input.xml\" -o \"C:\\Docs\\output.md\"\n```\n\n#### Batch conversion — search a directory tree\n\nSearches `C:\\Project\\Docs` for sub-folders named `Release`, converts every `.xml` found inside, and writes `.md` files to the output dir:\n\n```bat\n    XmlDocToMd.exe -s \"C:\\Project\\Docs\" -d \"Release\" -o \"C:\\Project\\MarkdownDocs\"\n```\n\n#### With a secondary (backup) output directory\n\n```bat\n    XmlDocToMd.exe -i \"C:\\Docs\\input.xml\" -o \"C:\\Docs\\Markdown\\output.md\" -l \"C:\\Backup\\Docs\"\n```\n\n#### Soft tag handling — warn instead of throwing\n\n```bat\n    XmlDocToMd.exe -i \"C:\\Docs\\input.xml\" -o \"C:\\Docs\\output.md\" -u Warn\n```\n\n#### GitHub-flavored URLs + README output\n\n```bat\n    XmlDocToMd.exe -i \"C:\\Docs\\input.xml\" -o \"C:\\Docs\\README.md\" -g -r\n```\n\n#### Visual Studio post-build event (XMLtoMD configuration)\n\n```xml\n    \u003cTarget Name=\"PostBuild\" AfterTargets=\"PostBuildEvent\" Condition=\"'$(ConfigurationName)' == 'XMLtoMD'\"\u003e\n      \u003cExec Command=\"call \u0026quot;$(TargetDir)$(TargetName).exe\u0026quot; -s \u0026quot;$(ProjectDir)\\\u0026quot; -d \u0026quot;$(ConfigurationName)\u0026quot; -o \u0026quot;$(ProjectDir)\\\u0026quot; -g -r\" /\u003e\n    \u003c/Target\u003e\n```\n\n### Supported XML Documentation Tags\n\n#### Standard C# XML Doc Tags\n\n|Tag|Markdown output|\n|---|---|\n|`doc`|Top-level document root — emits an `#` heading with the assembly name.|\n|`summary`|Rendered as a plain paragraph below the member heading.|\n|`remarks`|Rendered as a paragraph block below the summary.|\n|`returns`|Emits a **Returns:** line with the resolved return type.|\n|`value`|Emits a **Value:** line for property descriptions.|\n|`example`|Rendered under an `##### Example` sub-heading.|\n|`param`|Collected into a two-column Markdown table (Name / Description).|\n|`typeparam`|Collected into a two-column Generics table.|\n|`exception`|Emits a **Throws:** linked entry per exception type.|\n|`inheritdoc`|Emits *Inherited from `BaseType`*. The `cref` attribute controls the display name.|\n\n#### Cross-Reference Tags\n\n|Tag / attribute|Markdown output|\n|---|---|\n|`see cref=\"\"`|Inline hyperlink to the referenced member.|\n|`see langword=\"\"`|Renders the keyword as inline code, e.g. `null`, `true`.|\n|`see href=\"\"`|Currently not rendered as a link. Use `a href=\"\"` for explicit URL links.|\n|`seealso`|Appended to a *See also* bullet list at the end of the member block.|\n|`paramref`|Renders the parameter name as inline code.|\n|`typeparamref`|Renders the type-parameter name as inline code.|\n\n#### List Tags\n\n\u003e [!TIP]\n\u003e Use `type=\"table\"` for two-column reference tables, `type=\"number\"` for step-by-step instructions, and `type=\"bullet\"` (the default) for unordered lists.\n\n|Tag|Description|\n|---|---|\n|`list type=\"bullet\"`|Unordered bullet list — each `item` becomes a `-` entry.|\n|`list type=\"number\"`|Ordered list — each `item/description` becomes a numbered entry.|\n|`list type=\"table\"`|Pipe table — `listheader` provides column headers; each `item` becomes a row.|\n|`listheader`|Column header row for `type=\"table\"` lists.|\n|`item`|A single list entry; contains `term` and/or `description`.|\n|`term`|Bold label in a table row or bullet entry.|\n|`description`|Description text within an `item`.|\n\n#### Inline Formatting Tags\n\n|Tag|Markdown output|\n|---|---|\n|`c`|Inline code span: ``text``|\n|`tt`|Teletype / monospace — same output as `c`: ``text``|\n|`b`|**Bold** text: `**text**`|\n|`strong`|**Bold** text: `**text**`|\n|`i`|*Italic* text: `*text*`|\n|`u`|Currently rendered as bold text: `**text**`|\n|`para`|Paragraph break inside a block element.|\n|`code`|Fenced code block. Use the `lang` attribute for syntax highlighting, e.g. `lang=\"csharp\"`.|\n\n#### HTML Pass-Through Tags\n\n|Tag|Markdown output|\n|---|---|\n|`a href=\"…\"`|Hyperlink: `[text](url)`|\n|`br`|Hard line break.|\n|`h1` – `h4`|ATX headings at the corresponding level.|\n\n#### GFM Alert Blocks *(DocFX / Sandcastle compatibility)*\n\n\u003e [!NOTE]\n\u003e These tags map to GitHub-Flavored Markdown alert syntax (`\u003e [!NOTE]` etc.) and render as coloured callout boxes on GitHub and MkDocs Material.\n\n|Tag|GFM alert type|\n|---|---|\n|`note`|`\u003e [!NOTE]` — informational callout.|\n|`tip`|`\u003e [!TIP]` — helpful suggestion.|\n|`important`|`\u003e [!IMPORTANT]` — key information.|\n|`warning`|`\u003e [!WARNING]` — potential pitfall.|\n|`caution`|`\u003e [!CAUTION]` — dangerous action ahead.|\n\n---\n## ROBdk97.XmlDocToMd.Cli.Options\n\nCommand-line options for the XmlDocToMd converter.\n\nOptions are parsed by [CommandLineParser](https://github.com/commandlineparser/commandline) and can also be populated programmatically for testing or embedding purposes.\n\n|Flag|Purpose|\n|---|---|\n|`-i` / `--inputfile`|Single XML file to convert.|\n|`--cin`|Read XML input from standard input instead of a file.|\n|`-o` / `--outputfile`|Destination Markdown file.|\n|`--cout`|Write generated Markdown to standard output instead of a file.|\n|`-l` / `--secondaryDir`|Optional secondary output directory for copying generated Markdown.|\n|`-s` / `-d`|Batch mode: search directory + subdirectory name.|\n|`-u`|Unexpected-tag policy ([UnexpectedTagActionEnum](#robdk97xmldoctomdcliunexpectedtagactionenum)).|\n|`-g`|Use GitHub-Flavored Markdown anchor links.|\n|`-r`|Name the output file `README.md`.|\n|`-f`|Path to a custom `settings.json`.|\n\n**Properties**\n\n|Name|Type|Description|\n|---|---|---|\n|InputFile|String|Path to the input XML documentation file to convert. Mutually exclusive with `--cin`; when both are supplied, the file path takes precedence and ConsoleIn is ignored.|\n|ConsoleIn|Boolean|When `true`, reads the XML document from `stdin` instead of a file. Example: `type MyLib.xml \\| XmlDocToMd.exe --cin -o docs\\README.md`.|\n|OutputFile|String|Path of the Markdown file to write. In batch mode (`-s`/`-d`) this is treated as the output directory rather than a single file path.|\n|SecondaryOutputDirectory|String|Optional secondary output directory. The generated Markdown file is copied here after the primary write, for example to a network share or documentation repo.|\n|ConsoleOut|Boolean|When `true`, writes the Markdown output to `stdout` instead of a file.|\n|UnexpectedTagAction|[UnexpectedTagActionEnum](#robdk97xmldoctomdcliunexpectedtagactionenum)|Determines how XML tags that have no registered renderer are treated. Defaults to Error. Values: Error (throws and halts), Warn (writes WARN and continues), Accept (silently skips).|\n|SearchDirectory|String|Root directory to search for XML documentation files when running in batch mode. Must be combined with Directory (`-d`). Tip: point this at the project root and use `-d` for the build-output subfolder (for example `Release` or `XMLtoMD`).|\n|Directory|String|Name of the subdirectory within SearchDirectory that contains the compiled `.xml` and `.dll` files. Defaults to `\"Release\"`.|\n|Git|Boolean|When `true`, formats anchor links using GitHub-Flavored Markdown conventions (lower-case, hyphens instead of spaces). Tip: enable this when publishing to GitHub/GitLab so heading anchors resolve correctly.|\n|Readme|Boolean|When `true`, names the output file `README.md` instead of `{AssemblyName}.md`. Use together with `-g` when generating the landing-page documentation for a GitHub repository.|\n|RepositoryRootPath|String|Repository root used to resolve source-file links for GitHub-Flavored Markdown when a referenced type has no generated heading. If omitted, the converter tries to infer a suitable root from the search/input path.|\n|SettingsFile|String|Path to the JSON settings file that controls file and namespace exclusions. Defaults to `\"settings.json\"` in the working directory. If the file does not exist it is created automatically with empty default values. See [Settings](#robdk97xmldoctomdclisettings) for available properties.|\n\n---\n## ROBdk97.XmlDocToMd.Cli.Settings\n\nPersistent configuration loaded from a JSON file (`settings.json` by default).\n\nThe settings file is created automatically with empty defaults when it does not yet exist. The path can be overridden with the `-f` / `--settings` CLI option.\n\n**Properties**\n\n|Name|Type|Description|\n|---|---|---|\n|FilesToIgnore|List‹String›|File names (without path) that should be skipped during directory-wide conversion. Supports the wildcard `*`, for example `System*`, `Microsoft*`. Add system-generated XML files such as `System.Runtime.xml` to keep the output focused on your own assemblies.|\n|NameSpacesToRemove|List‹String›|Namespace fragments whose members are excluded from conversion. Any member whose fully-qualified name contains one of these strings is silently dropped before rendering begins. \u003e [!TIP] \u003e Use this to hide internal or generated namespaces such as `CompilerServices` or `Internal`.|\n\n---\n## ROBdk97.XmlDocToMd.Cli.UnexpectedTagActionEnum\n\nControls how the converter reacts to recoverable conversion problems, such as XML documentation tags without a registered [ITagRenderStrategy](Rendering/ITagRenderStrategy.cs) or other non-fatal rendering issues encountered while walking the XML tree.\n\nChoose the policy that best fits the maturity of your XML documentation:\n\u003e [!TIP]\n\u003e Start with Warn while authoring documentation, then switch to Error once all conversion issues are accounted for.\n\n**Fields**\n\n|Name|Type|Description|\n|---|---|---|\n|Error|[UnexpectedTagActionEnum](#robdk97xmldoctomdcliunexpectedtagactionenum)|Throws when a recoverable conversion problem is encountered, halting conversion immediately.|\n|Warn|[UnexpectedTagActionEnum](#robdk97xmldoctomdcliunexpectedtagactionenum)|Emits a `WARN: ` diagnostic to `stderr` via the configured [IWarningLogger](Logging/IWarningLogger.cs) and continues conversion, producing partial output.|\n|Accept|[UnexpectedTagActionEnum](#robdk97xmldoctomdcliunexpectedtagactionenum)|Silently ignores recoverable conversion problems. No diagnostic is emitted and no output is produced for the skipped element.|\n\n---\n\nGenerated by [XmlDocToMd](https://github.com/ROBdk97/XmlDocToMd) by [ROBdk97](https://github.com/ROBdk97)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobdk97%2Fxmldoctomd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobdk97%2Fxmldoctomd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobdk97%2Fxmldoctomd/lists"}