github/foam
1
1
Fork 0
mirror of https://github.com/foambubble/foam.git synced 2026-01-10 14:38:13 -05:00
Code Issues Packages Projects Releases Wiki Activity

refactor: move vscode tutorial

Browse Source
This commit is contained in:
Joe Previte
2020-07-06 17:50:42 -07:00
parent 05c8659368
commit f37310d764
2 changed files with 80 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/contribution-guide.md
View File

@@ -17,16 +17,6 @@ Foam is open to contributions of any kind, including but not limited to code, do
- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
- All other [[recommended-extensions]] live in their respective GitHub repos.
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[roadmap]: roadmap "Roadmap"
[principles]: principles "Principles"
[code-of-conduct]: code-of-conduct "Code of Conduct"
[recipes]: recipes "Recipes"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[//end]: # "Autogenerated link references"
## Contributing to the VS Code Extension
If you're interested in contributing to the VS Code extension (aka `foam-vscode`), this guide will help you get things set up locally.
@@ -44,69 +34,15 @@ If you're interested in contributing to the VS Code extension (aka `foam-vscode`
5. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from foam-template). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
6. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
### Tutorial: Adding a New Command
For more resources related to the VS Code Extension, check out the links below:
- [[Tutorial: Adding a New Command to the VS Code Extension]]
Let's try adding a new command to `foam-vscode`.
1. Navigate to `packages/foam-vscode/src/extension.ts`
2. Find the `activate` function
3. Register a new command:
```diff
export function activate(context: ExtensionContext) {
context.subscriptions.push(
commands.registerCommand(
"foam-vscode.update-wikilinks",
updateReferenceList
),
+ commands.registerCommand(
+ "foam-vscode.hello-friend",
+ () => {
+ . window.showInformationMessage("Hello, friend!);
+ }
+ ),
workspace.onWillSaveTextDocument(onWillSave),
languages.registerCodeLensProvider(
mdDocSelector,
new WikilinkReferenceCodeLensProvider()
)
);
}
```
4. Navigate to `packages/foam-vscode/package.json`
5. Add your command to the `contributes.commands` array:
```diff
"contributes": {
"commands": [
{
"command": "foam-vscode.update-wikilinks",
"title": "Foam: Update Markdown Reference List"
+ },
+ {
+ "command": "foam-vscode.hello-friend",
+ "title": "Foam: Hello Friend",
+ },
]
},
```
6. Press f5 to run the new extension host, or restart the extension host if it's already running.
7. Test out your new command. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Hello Friend". You should see an information pop up in the corner of the screen.
And that's how you add new commands! We look forward to your contributions.
More resources:
- [Your First Extension](https://code.visualstudio.com/api/get-started/your-first-extension)
- [`vscode-extension-samples`](https://github.com/microsoft/vscode-extension-samples)
### F.A.Q.
**How do I write a test for my extension addition?**
This is still a work in progress. We've opted for [Jest](https://jestjs.io/) as our testing framework. There are currently no end-to-end tests (contributions are welcome!). However, we would encourage you to write tests for anything that you can test. We're happy to discuss on PRs too!
**How do I know if using the local version of the Foam extension vs. the produciton one while testing locally?**
When you start the extension development host, the local version of the extension "shadows" or overrides any installed versions of the package with the same ID. So when you F5/start the extension host, you should always be running the local version, plus any other extensions your workspace/vscode is configured to run.
As far as we know, you can't run the "shadowed" base install while running the local extension
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[roadmap]: roadmap "Roadmap"
[principles]: principles "Principles"
[code-of-conduct]: code-of-conduct "Code of Conduct"
[recipes]: recipes "Recipes"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[//end]: # "Autogenerated link references"

69
docs/tutorial-adding-a-new-command-to-the-vs-code-extension.md Normal file
View File

@@ -0,0 +1,69 @@
# Tutorial Adding a New Command to the VS Code Extension
This tutorial will walk you through adding a new command to the VS Code extension.
Let's try adding a new command to `foam-vscode`.
1. Navigate to `packages/foam-vscode/src/extension.ts`
2. Find the `activate` function
3. Register a new command:
```diff
export function activate(context: ExtensionContext) {
context.subscriptions.push(
commands.registerCommand(
"foam-vscode.update-wikilinks",
updateReferenceList
),
+ commands.registerCommand(
+ "foam-vscode.hello-friend",
+ () => {
+ . window.showInformationMessage("Hello, friend!);
+ }
+ ),
workspace.onWillSaveTextDocument(onWillSave),
languages.registerCodeLensProvider(
mdDocSelector,
new WikilinkReferenceCodeLensProvider()
)
);
}
```
4. Navigate to `packages/foam-vscode/package.json`
5. Add your command to the `contributes.commands` array:
```diff
"contributes": {
"commands": [
{
"command": "foam-vscode.update-wikilinks",
"title": "Foam: Update Markdown Reference List"
+ },
+ {
+ "command": "foam-vscode.hello-friend",
+ "title": "Foam: Hello Friend",
+ },
]
},
```
6. Press f5 to run the new extension host, or restart the extension host if it's already running.
7. Test out your new command. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Hello Friend". You should see an information pop up in the corner of the screen.
And that's how you add new commands! We look forward to your contributions.
More resources:
- [Your First Extension](https://code.visualstudio.com/api/get-started/your-first-extension)
- [`vscode-extension-samples`](https://github.com/microsoft/vscode-extension-samples)
### F.A.Q.
**How do I write a test for my extension addition?**
This is still a work in progress. We've opted for [Jest](https://jestjs.io/) as our testing framework. There are currently no end-to-end tests (contributions are welcome!). However, we would encourage you to write tests for anything that you can test. We're happy to discuss on PRs too!
**How do I know if using the local version of the Foam extension vs. the produciton one while testing locally?**
When you start the extension development host, the local version of the extension "shadows" or overrides any installed versions of the package with the same ID. So when you F5/start the extension host, you should always be running the local version, plus any other extensions your workspace/vscode is configured to run.
As far as we know, you can't run the "shadowed" base install while running the local extension