{"id":19121077,"url":"https://github.com/dadhi/cstomd","last_synced_at":"2025-04-15T14:56:20.684Z","repository":{"id":40904968,"uuid":"148627904","full_name":"dadhi/CsToMd","owner":"dadhi","description":"Visual Studio extension and dotnet CLI tool to generate the Markdown Docs from the C# Tests keeping your Docs and Tests in sync!","archived":false,"fork":false,"pushed_at":"2025-04-13T21:15:34.000Z","size":1073,"stargazers_count":43,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-15T14:56:04.979Z","etag":null,"topics":["cli","documentation","documentation-generator","documentation-tool","dotnet","dotnet-tool","extension","filegenerator","markdown","runnable","samples","tools","visualstudio2017"],"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/dadhi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"zenodo":null},"funding":{"github":"dadhi"}},"created_at":"2018-09-13T11:29:04.000Z","updated_at":"2025-04-14T03:01:03.000Z","dependencies_parsed_at":"2024-11-16T13:04:07.290Z","dependency_job_id":"918f0c8a-821e-4d79-b6e0-6077eeda3274","html_url":"https://github.com/dadhi/CsToMd","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadhi%2FCsToMd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadhi%2FCsToMd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadhi%2FCsToMd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadhi%2FCsToMd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadhi","download_url":"https://codeload.github.com/dadhi/CsToMd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094937,"owners_count":21211836,"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":["cli","documentation","documentation-generator","documentation-tool","dotnet","dotnet-tool","extension","filegenerator","markdown","runnable","samples","tools","visualstudio2017"],"created_at":"2024-11-09T05:15:59.622Z","updated_at":"2025-04-15T14:56:20.672Z","avatar_url":"https://github.com/dadhi.png","language":"C#","funding_links":["https://github.com/sponsors/dadhi"],"categories":[],"sub_categories":[],"readme":"# CsToMd\n- [CsToMd](#cstomd)\n  - [Idea and Overview](#idea-and-overview)\n  - [Dotnet CLI tool](#dotnet-cli-tool)\n    - [Ad-hoc document generation](#ad-hoc-document-generation)\n    - [Build integration](#build-integration)\n  - [Visual Studio extension](#visual-studio-extension)\n    - [How to use](#how-to-use)\n\n\n## Idea and Overview\n\n[![NuGet Badge](https://img.shields.io/nuget/v/dotnet-cstomd.svg)](https://nuget.org/packages/dotnet-cstomd)\n\nThe [dotnet CLI tool](https://www.nuget.org/packages/dotnet-cstomd) to convert C# file with Unit Tests into the [Markdown](https://guides.github.com/features/mastering-markdown) documentation.\n\nThe idea is to have a normal C# .cs file with the special comments `/*md`, `md*/`, and `//md` which will be stripped when converting the file into the respective Markdown .md file. There are a couple of additional features but this is basically it. \n\nNow you have **the documentation always up-to-date with the runnable samples** in the normal .NET Test library project with NUnit, XUnit, etc.\n\nYou may check the DryIoc [documentation project](https://github.com/dadhi/DryIoc/tree/master/docs/DryIoc.Docs) for the real-world case example.\n\nThe additional features:\n\n- Directive to automatically wrap code in code fence with the optional language, e.g. add `//md code:csharp`, or just `//md code:` to add fences, and `//md code:--` to stop adding fences. The directive may be used multiple times through the file.\n- Converting the section outlined with `//md{` and `//md}` comments into the [collapsed markdown details](https://gist.github.com/pierrejoubert73/902cc94d79424356a8d20be2b382e1ab).\n- The optional `cstomd.config` file in the folder with the lines starters to be removed completely from the generated documentation file.\n\n\n## Dotnet CLI tool\n\nThe [dotnet-cstomd](https://www.nuget.org/packages/dotnet-cstomd) is a [dotnet CLI tool](https://docs.microsoft.com/en-us/dotnet/core/tools/). It may be called from the command line and from the MSBuild scripts (**enabling the document generation in the build pipeline**).\n\nI addition the dotnet tool enables the documentation development in the **Visual Studio Code**.\n\n![VSCode usage](https://github.com/dadhi/CsToMd/blob/master/screen3.png?raw=true)\n\n\n### Ad-hoc document generation\n\n- Install the dotnet-cstomd globally from the nuget, e.g. in the shell of your choice `dotnet tool install --global dotnet-cstomd --version 1.2.1`. Now you can invoke `cstomd MyClass.cs` directly and get the `MyClass.md` output.\n\n\n### Build integration\n\n  * Switch to your project: `cd path\\to\\MyProject`\n  * Add the tool manifest file: `dotnet new tool-manifest`\n  * Install the tool: `dotnet tool install dotnet-cstomd --version 1.2.1 --roll-forward` (the manifest file will be updated and later used for restore)\n  * Add the section to your project:\n\n    ```xml\n    \u003cItemGroup\u003e\n        \u003cDocFile Include=\"**\\*.cs\" /\u003e\n    \u003c/ItemGroup\u003e\n\n    \u003cTarget Name=\"MdGenerate\" BeforeTargets=\"BeforeBuild\"\u003e\n        \u003cExec WorkingDirectory=\"$(ProjectDir)\" Command=\"dotnet cstomd %(DocFile.Identity)\" /\u003e\n    \u003c/Target\u003e\n    ```\n    You may check the DryIoc [documentation project file](https://github.com/dadhi/DryIoc/blob/6f466ee1b4fde548c7211ecb0a54655011f69e57/docs/DryIoc.Docs/DryIoc.Docs.csproj#L26) for the real-world case example.\n\n  * You may run the document generation target without the rest of the build:\n   ```\n    dotnet msbuild -target:MdGenerate path\\to\\MyProject\\MyProject.csproj\n   ```\n   You may create a helper shell script with the command above.\n\n  \n  Here is the [MS tutorial](https://docs.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use#:~:text=Create%20a%20manifest%20file,-To%20install%20a\u0026text=The%20output%20indicates%20successful%20creation%20of%20the%20file.\u0026text=The%20template%20%22Dotnet%20local%20tool%20manifest%20file%22%20was%20created%20successfully.\u0026text=The%20tools%20listed%20in%20a,the%20one%20that%20contains%20the%20.) for installing and using the local tools.\n \n\n## Visual Studio extension\n\nThis extension for Visual Studio 2019+ contains the CustomTool File Generator.\n\nWhen applied to the C# source file it looks like this:\n\n![Screenshot](screenshot_vsix_v2_1_0.png)\n\n\n### How to use\n\n- Install [the extension](https://marketplace.visualstudio.com/items?itemName=dadhi.cstomd123) directly from the marketplace in Visual Studio or download the extension vsix file from the [release page](https://github.com/dadhi/CsToMd/releases/tag/v2.1.0).\n- In properties of your .cs file set the `CustomTool` property to `CsToMd`.\n- Save the .cs file\n- Check the generated .md file under the .cs file in Solution Explorer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadhi%2Fcstomd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadhi%2Fcstomd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadhi%2Fcstomd/lists"}