{"id":13607354,"url":"https://github.com/SimonCropp/MarkdownSnippets","last_synced_at":"2025-04-12T11:32:20.763Z","repository":{"id":34083075,"uuid":"169644230","full_name":"SimonCropp/MarkdownSnippets","owner":"SimonCropp","description":"Extracts snippets from code files and merges them into markdown documents.","archived":false,"fork":false,"pushed_at":"2024-11-02T00:36:34.000Z","size":2613,"stargazers_count":195,"open_issues_count":5,"forks_count":24,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-06T19:32:08.935Z","etag":null,"topics":[],"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/SimonCropp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"license.txt","code_of_conduct":"code_of_conduct.md","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},"funding":{"github":"SimonCropp"}},"created_at":"2019-02-07T21:18:54.000Z","updated_at":"2024-11-06T00:36:37.000Z","dependencies_parsed_at":"2024-02-16T12:25:55.797Z","dependency_job_id":"ff503ec9-2d69-418e-88e3-580e35920cac","html_url":"https://github.com/SimonCropp/MarkdownSnippets","commit_stats":{"total_commits":1488,"total_committers":15,"mean_commits":99.2,"dds":0.3353494623655914,"last_synced_commit":"cd439628c0a849bb08b8191a85cb66bc78a854f0"},"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCropp%2FMarkdownSnippets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCropp%2FMarkdownSnippets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCropp%2FMarkdownSnippets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCropp%2FMarkdownSnippets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimonCropp","download_url":"https://codeload.github.com/SimonCropp/MarkdownSnippets/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223514176,"owners_count":17158140,"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":[],"created_at":"2024-08-01T19:01:17.908Z","updated_at":"2024-11-07T12:32:03.931Z","avatar_url":"https://github.com/SimonCropp.png","language":"C#","funding_links":["https://github.com/sponsors/SimonCropp"],"categories":["C# #"],"sub_categories":[],"readme":"\u003c!--\nGENERATED FILE - DO NOT EDIT\nThis file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).\nSource File: /readme.source.md\nTo change this file edit the source file and then run MarkdownSnippets.\n--\u003e\n\n# \u003cimg src=\"/src/icon.png\" height=\"30px\"\u003e MarkdownSnippets\n\n[![Build status](https://ci.appveyor.com/api/projects/status/8ijthhby6mhw8fk3/branch/main?svg=true)](https://ci.appveyor.com/project/SimonCropp/MarkdownSnippets)\n[![NuGet Status](https://img.shields.io/nuget/v/MarkdownSnippets.Tool.svg?label=dotnet%20tool)](https://www.nuget.org/packages/MarkdownSnippets.Tool/)\n[![NuGet Status](https://img.shields.io/nuget/v/MarkdownSnippets.MsBuild.svg?label=MsBuild%20Task)](https://www.nuget.org/packages/MarkdownSnippets.MsBuild/)\n[![NuGet Status](https://img.shields.io/nuget/v/MarkdownSnippets.svg?label=.net%20API)](https://www.nuget.org/packages/MarkdownSnippets/)\n\nA [dotnet tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) that extract snippets from code files and merges them into markdown documents.\n\n**See [Milestones](../../milestones?state=closed) for release notes.**\n\n**[.net 8](https://dotnet.microsoft.com/download/dotnet/8.0) or higher is required to run this tool.**\n\n\n## Value Proposition\n\nAutomatically extract snippets from code and injecting them into markdown documents has several benefits:\n\n * Snippets can be verified by a compiler or parser.\n * Tests can be run on snippets, or snippets can be pulled from existing tests.\n * Changes in code are automatically reflected in documentation.\n * Snippets are less likely to get out of sync with the main code-base.\n * Snippets in markdown is easier to create and maintain since any preferred editor can be used to edit them.\n\n\n## Behavior\n\n * Recursively scan the target directory for code files containing snippets. (See [exclusion](/docs/exclusion.md)).\n * Recursively scan the target directory for markdown (`.md` or `mdx`) files. (See [Document Scanning](#document-convention)).\n * Merge the snippets into those markdown files.\n\n\n## Installation\n\nEnsure [dotnet CLI is installed](https://docs.microsoft.com/en-us/dotnet/core/tools/).\n\nInstall [MarkdownSnippets.Tool](https://nuget.org/packages/MarkdownSnippets.Tool/)\n\n```ps\ndotnet tool install -g MarkdownSnippets.Tool\n```\n\n\n## Usage\n\n```ps\nmdsnippets C:\\Code\\TargetDirectory\n```\n\nIf no directory is passed the current directory will be used, but only if it exists with a git repository directory tree. If not an error is returned.\n\n\n### Document Convention\n\nThere are two approaches scanning and modifying markdown files.\n\n\n#### SourceTransform\n\nThis is the default.\n\n\n##### source.md file\n\nThe file convention recursively scans the target directory for all `*.source.md` files. Once snippets are merged the `.source.md` to produce `.md` files. So for example `readme.source.md` would be merged with snippets to produce `readme.md`. Note that this process will overwrite any existing `.md` files that have matching `.source.md` files.\n\n\n#### mdsource directory\n\nThere is a secondary convention that leverages the use of a directory named `mdsource`. Where `.source.md` files are placed in a `mdsource` sub-directory, the `mdsource` part of the file path will be removed when calculating the target path. This allows the `.source.md` to be grouped in a sub directory and avoid cluttering up the main documentation directory.\n\nWhen using the `mdsource` convention, all references to other files, such as links and images, should specify the full path from the root of the repository. This will allow those links to work correctly in both the source and generated markdown files. Relative paths cannot work for both the source and the target file.\n\n\n#### InPlaceOverwrite\n\nRecursively scans the target directory for all `*.md` files and merges snippets into those files.\n\n\n##### Command line\n\n```ps\nmdsnippets -c InPlaceOverwrite\n```\n\n```ps\nmdsnippets --convention InPlaceOverwrite\n```\n\n\n##### Config file\n\nCan be enabled in [mdsnippets.json config file](/docs/config-file.md).\n\n```json\n{\n  \"Convention\": \"InPlaceOverwrite\"\n}\n```\n\n\n#### Moving from SourceTransform to InPlaceOverwrite\n\n * Ensure `\"WriteHeader\": false` is used in `mdsnippets.json`.\n * Ensure `\"ReadOnly\": false` is used in `mdsnippets.json`.\n * Ensure using the current stable version and a docs generation has run.\n * Delete all `.source.md` files.\n * Modify `mdsnippets.json` to add `\"Convention\": \"InPlaceOverwrite\"`.\n * Run the docs generation.\n\n\n### Mark resulting files as read only\n\nTo mark the resulting documents files as read only use `-r` or `--read-only`.\n\nThis can be helpful in preventing incorrectly editing the documents file instead of the `.source.` file conventions.\n\n```ps\nmdsnippets -r true\n```\n\n```ps\nmdsnippets --read-only true\n```\n\n\n## Defining Snippets\n\nAny code wrapped in a convention based comment will be picked up. The comment needs to start with `begin-snippet:` which is followed by the key. The snippet is then terminated by `end-snippet`.\n\n```\n// begin-snippet: MySnippetName\nMy Snippet Code\n// end-snippet\n```\n\nNamed [C# regions](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-region) will also be picked up, with the name of the region used as the key.\n\nTo stop regions collapsing in Visual Studio [disable 'enter outlining mode when files open'](/docs/stop-regions-collapsing.png). See [Visual Studio outlining](https://docs.microsoft.com/en-us/visualstudio/ide/outlining).\n\n\n### UrlsAsSnippets\n\nUrls to files to be included as snippets. Space ` ` separated for multiple values.\n\nEach url will be accessible using the file name as a key. Any snippets within the files will be extracted and accessible as individual keyed snippets.\n\n```ps\nmdsnippets --urls-as-snippets \"https://github.com/SimonCropp/MarkdownSnippets/snippet.cs\"\n```\n\n```ps\nmdsnippets -u \"https://github.com/SimonCropp/MarkdownSnippets/snippet.cs\"\n```\n\n\n## Using Snippets\n\nThe keyed snippets can be used in any documentation `.md` file by adding the text `snippet: KEY`.\n\nThen snippets with that key.\n\nFor example\n\n\u003cpre\u003e\nSome blurb about the below snippet\nsnippet\u0026#58; MySnippetName\n\u003c/pre\u003e\n\nThe resulting markdown will be:\n\n    \u003c!-- snippet: MySnippetName --\u003e\n    Some blurb about the below snippet\n    \u003ca id='snippet-MySnippetName'\u003e\u003c/a\u003e\n    ```\n    My Snippet Code\n    ```\n    \u003csup\u003e\u003ca href='/relativeUrlToFile#L1-L11' title='Snippet source file'\u003esnippet source\u003c/a\u003e | \u003ca href='#snippet-MySnippetName' title='Start of snippet'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n    \u003c!-- endSnippet --\u003e\n\nNotes:\n\n * The vertical bar ( | ) is used to separate adjacent links as per web accessibility recommendations: https://webaim.org/techniques/hypertext/hypertext_links#groups\n * [H33: Supplementing link text with the title attribute](https://www.w3.org/TR/WCAG20-TECHS/H33.html)\n\n\n### Including a snippet from the web\n\nSnippets that start with `http` will be downloaded and the contents rendered. For example:\n\n    snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt\n\nWill render:\n\n\t\u003c!-- snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt --\u003e\n\t\u003ca id='snippet-https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt'\u003e\u003c/a\u003e\n\t```txt\n\tThe MIT License (MIT)\n\t...\n\t```\n\t\u003csup\u003e\u003ca href='#snippet-https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt' title='Snippet source file'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n\t\u003c!-- endSnippet --\u003e\n\nFiles are downloaded to `%temp%MarkdownSnippets` with a maximum of 100 files kept.\n\n\n### Including a full file\n\nIf no snippet is found matching the defined name. The target directory will be searched for a file matching that name. For example:\n\n    snippet: license.txt\n\nWill render:\n\n\t\u003c!-- snippet: license.txt --\u003e\n\t\u003ca id='snippet-license.txt'\u003e\u003c/a\u003e\n\t```txt\n\tThe MIT License (MIT)\n\t...\n\t```\n\t\u003csup\u003e\u003ca href='#snippet-license.txt' title='Start of snippet'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n\t\u003c!-- endSnippet --\u003e\n\n\n### LinkFormat\n\nDefines the format of `snippet source` links that appear under each snippet.\n\n\n#### Command line\n\n```ps\nmdsnippets --link-format Bitbucket\n```\n\n```ps\nmdsnippets -l Bitbucket\n```\n\n\n#### Values\n\n\u003c!-- snippet: LinkFormat.cs --\u003e\n\u003ca id='snippet-LinkFormat.cs'\u003e\u003c/a\u003e\n```cs\nnamespace MarkdownSnippets;\n\npublic enum LinkFormat\n{\n    GitHub,\n    Tfs,\n    Bitbucket,\n    GitLab,\n    DevOps,\n    None\n}\n```\n\u003csup\u003e\u003ca href='/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L11' title='Snippet source file'\u003esnippet source\u003c/a\u003e | \u003ca href='#snippet-LinkFormat.cs' title='Start of snippet'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n\u003c!-- endSnippet --\u003e\n\nLink format `None` will omit the source link but still keep the snippet anchor.\n\n\n### OmitSnippetLinks\n\nThe links below a snippet can be omitted.\n\n\n#### Command line\n\n```ps\nmdsnippets --omit-snippet-links true\n```\n\n\n#### Config file\n\n```\n{\n  \"OmitSnippetLinks\": true\n}\n```\n\n\n#### How links are constructed\n\n\u003c!-- snippet: BuildLink --\u003e\n\u003ca id='snippet-BuildLink'\u003e\u003c/a\u003e\n```cs\nswitch (linkFormat)\n{\n    case LinkFormat.GitHub:\n        Polyfill.Append(builder, $\"{path}#L{snippet.StartLine}-L{snippet.EndLine}\");\n        return;\n    case LinkFormat.Tfs:\n        Polyfill.Append(builder, $\"{path}\u0026line={snippet.StartLine}\u0026lineEnd={snippet.EndLine}\");\n        return;\n    case LinkFormat.Bitbucket:\n        Polyfill.Append(builder, $\"{path}#lines={snippet.StartLine}:{snippet.EndLine}\");\n        return;\n    case LinkFormat.GitLab:\n        Polyfill.Append(builder, $\"{path}#L{snippet.StartLine}-{snippet.EndLine}\");\n        return;\n    case LinkFormat.DevOps:\n        Polyfill.Append(builder, $\"?path={path}\u0026line={snippet.StartLine}\u0026lineEnd={snippet.EndLine}\u0026lineStartColumn=1\u0026lineEndColumn=999\");\n        return;\n    case LinkFormat.None:\n        throw new($\"Unknown LinkFormat: {linkFormat}\");\n}\n```\n\u003csup\u003e\u003ca href='/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L96-L117' title='Snippet source file'\u003esnippet source\u003c/a\u003e | \u003ca href='#snippet-BuildLink' title='Start of snippet'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n\u003c!-- endSnippet --\u003e\n\n\n### UrlPrefix\n\nUrlPrefix allows a string to be defined that will prefix all snippet links. This is helpful when the markdown file are being hosted on a site that is not co-located with the source code files. It can be defined in the [config file](/docs/config-file.md), the [MsBuild task](/docs/msbuild.md), and the dotnet tool.\n\n\n#### Command line\n\n```ps\nmdsnippets --url-prefix \"TheUrlPrefix\"\n```\n\n\n#### Config file\n\n```\n{\n  \"UrlPrefix\": \"TheUrlPrefix\"\n}\n```\n\n\n## Add to Windows Explorer\n\nUse [src/context-menu.reg](context-menu.reg) to add MarkdownSnippets to the Windows Explorer context menu.\n\n\u003c!-- snippet: context-menu.reg --\u003e\n\u003ca id='snippet-context-menu.reg'\u003e\u003c/a\u003e\n```reg\nWindows Registry Editor Version 5.00\n[HKEY_CLASSES_ROOT\\Directory\\Shell]\n@=\"none\"\n[HKEY_CLASSES_ROOT\\Directory\\shell\\mdsnippets]\n\"MUIVerb\"=\"run mdsnippets\"\n\"Position\"=\"bottom\"\n[HKEY_CLASSES_ROOT\\Directory\\Background\\shell\\mdsnippets]\n\"MUIVerb\"=\"run mdsnippets\"\n\"Position\"=\"bottom\"\n[HKEY_CLASSES_ROOT\\Directory\\shell\\mdsnippets\\command]\n@=\"cmd.exe /c mdsnippets \\\"%V\\\"\"\n[HKEY_CLASSES_ROOT\\Directory\\Background\\shell\\mdsnippets\\command]\n@=\"cmd.exe /c mdsnippets \\\"%V\\\"\"\n```\n\u003csup\u003e\u003ca href='/src/context-menu.reg#L1-L13' title='Snippet source file'\u003esnippet source\u003c/a\u003e | \u003ca href='#snippet-context-menu.reg' title='Start of snippet'\u003eanchor\u003c/a\u003e\u003c/sup\u003e\n\u003c!-- endSnippet --\u003e\n\n\n## More Documentation\n\n  * Developer Information\u003c!-- include: doc-index. path: /docs/mdsource/doc-index.include.md --\u003e\n    * [.net API](/docs/api.md)\n    * [MsBuild Task](/docs/msbuild.md)\n    * [Github Action](/docs/github-action.md)\n  * Customisation\n    * [Config file convention](/docs/config-file.md)\n    * [Max Width](/docs/max-width.md)\n    * [Includes](/docs/includes.md)\n    * [Directory Exclusion](/docs/exclusion.md)\n    * [Header](/docs/header.md)\n  * Writing Documentation\n    * [Indentation](/docs/indentation.md)\n    * [Table of contents](/docs/toc.md)\u003c!-- endInclude --\u003e\n\n\n## Credits\n\nLoosely based on some code from https://github.com/shiftkey/scribble.\n\n\n## Icon\n\n[Down](https://thenounproject.com/AlfredoCreates/collection/arrows-5-glyph/) by [Alfredo Creates](https://thenounproject.com/AlfredoCreates) from [The Noun Project](https://thenounproject.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonCropp%2FMarkdownSnippets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSimonCropp%2FMarkdownSnippets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonCropp%2FMarkdownSnippets/lists"}