View on GitHub

vscode-didact

Didact Gives Your Readme Superpowers!

Writing a Didact Tutorial

Whether you choose to go with Markdown or AsciiDoc, you have a lot of tools at your disposal.

Essentially, you are just writing a document and then adding some Didact links to trigger VS Code functionality from within it. So let’s write a Didact tutorial that walks somebody through opening the Command Palette in VS Code.

Starting a File

To get started, you can create a Markdown file or an AsciiDoc file in VS Code, but make sure that the file extensions are .didact.md or .didact.adoc for easier previewing in the Didact window. Let’s call it code-palette.didact.md for now.

The Command Palette is something I struggled with initially, but now I use without thinking. It’s an important part of the VS Code environment and something new developers should learn to make their lives easier.

And you can start with this text:

# Accessing Commands in Visual Studio Code

Though Visual Studio Code is, at heart, a code editor, it employs a command API under the covers that does everything from opening views and files to creating and manipulating integrated terminals. It's an amazingly powerful framework and it's available at your fingertips!

How do you access this amazing functionality? The Command Palette!

## Writing a Tutorial to Access the Command Palette

The most important key combination to know is `Ctrl+Shift+P` (or `F1` on some platforms), which brings up the Command Palette. From here, you have access to all of the functionality of VS Code, including keyboard shortcuts for the most common operations.

Open the Command Palette now, using `Ctrl+Shift+P` on your keyboard.

Let’s add a Didact link to show the user what happens when they trigger the key bindings to open the Command Palette.

We can add some text like: Or click here to see the Command Palette in action. And then we’ll add a Didact link to open the palette.

When writing Didact tutorials, a useful tool in VS Code is the Keyboard Shortcuts window. You can bring that up by using the the File -> Preferences -> Keyboard Shortcuts menu. See the Visual Studio Docs for more details!

In the search box at the top, type “Show All Commands” and it will filter down the enormous list of commands and available keybindings in the environment. You should see at least one binding for Ctrl+Shift+P, depending on your operating system (you may also see F1). Both should be bound to the command workbench.action.showCommands. You can right-click on the binding and select Copy Command ID to stash that ID. We will need it next.

As you may have seen in the Constructing Didact Links page, a Didact link is composed of three main parts:

So for our purposes, we are just calling the command with nothing passed to it. That would look like:

Back in our Markdown text, we can create a link in that last sentence we added that looks like this:

Or [click here](didact://?commandId=workbench.action.showCommands) to see the Command Palette in action.

For simple commands, that’s all that necessary, so save your file.

To open and test your Didact file, right-click on the file (*.didact.md or *.didact.adoc) and select Start Didact Tutorial from File from the context menu or launch the Didact window while editing the file with Ctrl+Alt+D or Cmd+Alt+D.

If you click the click here link in your file, it should automatically open the Command Palette for you, just like we wanted it to.

Congratulations! You’ve created your first Didact tutorial with an active link!

Finishing Touches

To polish up your Didact link, you can do some additional things:

With those three options, it would look like:

Or [click here](didact://?commandId=workbench.action.showCommands&completion=Opened%20Command%20Palette. "Triggers the Show Commands command to open the Command Palette"){.didact} to see the Command Palette in action.