{"id":20931373,"url":"https://github.com/adr/vscode-adr-manager-introduction","last_synced_at":"2025-06-26T02:02:54.935Z","repository":{"id":86878660,"uuid":"527548733","full_name":"adr/vscode-adr-manager-introduction","owner":"adr","description":"This repository serves as a short introduction to the features of the VS Code extension for the ADR Manager.","archived":false,"fork":false,"pushed_at":"2022-08-22T16:00:30.000Z","size":2068,"stargazers_count":14,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-26T02:01:54.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-08-22T12:11:33.000Z","updated_at":"2025-03-09T13:12:55.000Z","dependencies_parsed_at":"2023-05-29T16:15:12.605Z","dependency_job_id":null,"html_url":"https://github.com/adr/vscode-adr-manager-introduction","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adr/vscode-adr-manager-introduction","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fvscode-adr-manager-introduction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fvscode-adr-manager-introduction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fvscode-adr-manager-introduction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fvscode-adr-manager-introduction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adr","download_url":"https://codeload.github.com/adr/vscode-adr-manager-introduction/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fvscode-adr-manager-introduction/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261984645,"owners_count":23240302,"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-11-18T21:41:46.527Z","updated_at":"2025-06-26T02:02:54.877Z","avatar_url":"https://github.com/adr.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction to the VS Code Extension for the ADR Manager\n\nThis repository serves as a short introduction to the features of the Visual Studio Code (VS Code) extension for the ADR Manager. For more information, please go to the [VS Code Marketplace page of the extension](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager).\n\n\n\u003chr\u003e\n\n## Prerequisites\n\n* Install [VS Code](https://code.visualstudio.com)\n* Install the [VS Code Extension for the ADR Manager](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager)\n* Download this repository to your local computer\n* Open the root folder of this repository in a VS Code instance. The folder `vscode-adr-manager-introduction` should be the only root folder in your current workspace.\n\nYour VS Code workspace should look something like this: \n\n\u003cimg src=\"images/workspace.png\" alt=\"VS Code workspace after opening repo folder\" width=\"250\"/\u003e\n\nFeel free to open your own directory to experiment with the extension!\n\n\u003chr\u003e\n\n## Features\n\n### Commands\n\nADR Manager provides several commands that can be accessed via the Command Palette (`Ctrl+Shift+P` on Windows/Linux, `Cmd+Shift+P` on macOS). Commands provided by this extension will be prefixed by `ADR Manager:`.\n\nADR Manager currently provides the following commands:\n\n\n#### Open ADR Manager\n\n\u003cimg src=\"images/main-webview.png\" alt=\" \" width=\"800\"/\u003e\n\n_Main webview of the ADR Manager._\n\n\u003cbr/\u003e\n\nWhen executing this command, the extension will open the main webview panel of the extension which lists every ADR in the ADR Directory it could find. From here, you may add and edit ADRs using the provided editor, or delete ADRs (i.e., move them to the trash can). If the user decides to edit an ADR, the extension will try to open another webview which shows the extension's ADR editor, prefilled with the data from that particular ADR.\n\nThe user can configure his preferred editor modes for adding and viewing ADRs based on the grade of detail in VS Code's settings.\n\n```\nTry to open the main webview and experiment with adding, editing and deleting ADRs.\nSee how these actions affect the file contents and the workspace!\n```\n\n\u003cbr/\u003e\n\n#### Add New ADR\n\n\u003cimg src=\"images/add-webview.png\" alt=\" \" width=\"800\"/\u003e\n\n_ADR editor provided by the ADR Manager._\n\n\u003cbr/\u003e\n\nWhen executing this command (or when clicking on the `Add ADR` button on the main webview), the extension will open a webview panel where the user can create a new ADR using the editor provided by the extension. The user may switch between editor modes to reveal or hide fields of the ADR based on the user's needs.\n\n\u003cbr/\u003e\n\n#### Open ADR Manager on This File\n\nWhen executing this command, the extension will try to open the ADR editor and fill it with information according to the content of the Markdown file that is currently in the active text editor of VS Code. If the Markdown file does not conform to MADR, the extension will show an error message.\n\nThis command works regardless of the location of the Markdown file, i.e., the Markdown file does not have to be located inside of the ADR Directory, although the extension will inform the user if that's the case (for consistency's sake).\n\n**Note**: This command will only show in the command palette if the currently opened Markdown file loosely follows the naming conventions of MADR. See the extension's page on the Marketplace for the exact criteria.\n\n```\nTry opening a valid MADR in 'docs/decisions' in the VS Code text editor and executing this command.\nTry the same with 'docs/decisions/0004-invalid-madr.md' and see what happens!\n```\n\n\u003cbr/\u003e\n\n#### Change ADR Directory\n\nWhen executing this command, the extension will ask the user to type in a path to the new/preferred ADR Directory. This path must be a relative path relative to the root folder(s) of the workspace.\n\n**Example**: If the root folder of the workspace is 'vscode-adr-manager-introduction' and I enter 'path/to/my/adr-directory', the resulting ADR Directory will be located at 'vscode-adr-manager-introduction/path/to/my/adr-directory/'.\n\nThe ADR Directory can also be changed in the settings.\n\n```\nTry opening the main webview of the ADR Manager.\nThen, change the ADR Directory from 'docs/decisions' to 'another-docs/decisions' and see what happens!\n```\n\n\u003cbr/\u003e\n\n#### Initialize ADR Directory\n\nWhen executing this command, the extension will try to create the ADR Directory specified by the user. Additionally, the extension will fill the ADR Directory with some useful files to start using MADR.\n\nIf the ADR Directory already exists in the workspace, the extension will notify the user.\n\n```\nTry changing the ADR Directory to a new directory not present in this repository and executing this command.\nTry executing the same command again immediately after and see what happens!\n```\n\n\u003chr\u003e\n\n### Menus\n\nADR Manager provides entries in the context menu of specific files and folders in the VS Code file explorer (i.e., when right-clicking on specific files or folders).\n\n\n#### Open ADR Manager\n\n\u003cimg src=\"images/context-menu-folder.png\" alt=\" \" width=\"400\"/\u003e\n\n_Context menu of the ADR Directory._\n\n\u003cbr/\u003e\n\nWhen opening the context menu for the ADR Directory or any folder along the way to the ADR Directory, there will be a new entry `Open ADR Manager` at the bottom of the context menu. Upon clicking that entry, the extension will execute the command [Open ADR Manager](#open-adr-manager), showing the main webview of the extension.\n\n```\nWhile the ADR Directory is set to 'docs/decisions', try to right-click on either 'docs' or 'decisions'\nin the file explorer and look for the new entry.\n```\n\n\u003cbr/\u003e\n\n#### Open ADR Manager on This File\n\n\u003cimg src=\"images/context-menu-file.png\" alt=\" \" width=\"400\"/\u003e\n\n_Context menu of a MADR file._\n\n\u003cbr/\u003e\n\nWhen opening the context menu for a Markdown file that loosely follows the MADR naming conventions, there will be a new entry `Open ADR Manager on This File` at the bottom of the context menu. Upon clicking that entry, the extension will execute the command [Open ADR Manager on This File](#open-adr-manager-on-this-file) on the specified file.\n\n```\nTry to right-click any MADR in 'docs/decision' in the file explorer and look for the new entry.\nTry to right-click this 'README.md' file and see what happens!\n```\n\n\u003chr\u003e\n\n### Linting\n\nADR Manager also provides some basic linting rules when editing a Markdown file that loosely follows the MADR naming conventions in the VS Code text editor. These linting rules may help the user to resolve issues with the extension not being able to parse an ADR in the ADR Directory.\n\n```\nThe file 'docs/decisions/0004-invalid-madr.md' cannot be edited in the editor provided by the extension.\nTry to open the file in the VS Code text editor and try to fix all errors.\nThen try again to edit the file via the editor provided by the extension.\n```\n\n\u003chr\u003e\n\n### Snippets\n\nADR Manager provides two snippets that help the user to create MADRs via the VS Code text editor. These snippets insert MADR templates into Markdown files such that the user only has to fill out the fields of the MADR. The user can use the `Tab` key to jump to the next field until all fields have been filled out.\n\nTo insert a snippet, the user has to open a Markdown file and manually trigger IntelliSense (`Ctrl+Space`) and look for the keyword, or type in the keyword (or parts of it) to automatically trigger IntelliSense.\n\n#### Basic MADR Template\n\nThis snippet inserts a MADR template at the cursor's current position that contains only the required fields of a MADR. The keyword for this snippet 'basic-madr'.\n\n#### Professional MADR Template\n\nThis snippet inserts a MADR template at the cursor's position that contains all available fields of a MADR.\nThe keyword for this snippet is 'professional-madr'\n\n```\nCreate a new Markdown file anywhere in the workspace.\nTry to insert either of these snippets with IntelliSense. \nTry filling out the fields with 'tabbing' to the next field.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fvscode-adr-manager-introduction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadr%2Fvscode-adr-manager-introduction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fvscode-adr-manager-introduction/lists"}