DEV Community: Wojciech Rithaler

Configuring VSCodeVim

Wojciech Rithaler — Sun, 19 May 2024 22:37:43 +0000

I decided to write this article because recently I have spent a long time learning and configuring VSCode. My new workplace has a strict software policy, making it my only option.
Configuring VSCode up to my liking turned out to be harder and more time consuming than expected. Maybe this article will help others and save someone their time.

1. About the article

This article is mostly for people who:

want to try Vim but are not yet ready to jump head first and switch
are already using VsCodeVim and are looking for configuration suggestions
are interested in how far can you push the VSCode to be Vim like

It contains information about the basic setup and configuration process of VSCodeVim as well as "keybinding conditions", tips, tricks and personal configuration.

** TLDR **

Check Anson Heung's article if you want a shorter version with most important keybindings and settings.

Instal VSCodeVim and create files settings.json and keybindings.json in User directory if necessary.

Jump directly to section 5 of this article or check my GitHub repo for personal config.

2. Prerequisites

First, the VSCodeVim plugin has to be installed and files settings.json and keybindings.json have to exist in the User directory.

The easiest way to get to those files is to click the "gear icon" of the extension and select option "Extension keyboard shortcuts" or "Extension settings". In both cases a new setting tab will open. Clicking "Open Settings (JSON)" should allow editing appropriate files.

It is also crucial to understand the naming convention.

Note!

Image and more information can be found here

Activity bar is comprised of "Views". By default there are five views:

Explorer
Search
Source Control
Run and Debug
Extensions

Editor group is comprised of "tabs".

A small code outline on the right side is called "minimap".

A fragmented path below editor groups is called "breadcrumbs".

3. More on settings.json and keybindings.json

Among people I have worked with, most have never configured their VSCode that is why a short introduction could be useful.

Settings.json is a general VSCode configuration file and representation of all setting changes. It should contain information about setting changes, theme changes, extension setting changes and most importantly for this article VSCodeVim configuration and keybindings.
Keybindings.json is a general VSCode configuration file that holds information about keybindings changed by the user.

Note!

I try to follow a rule - if a key binding is related to Vim, or performs similar action (for example uses a Leader key), then it should be placed in settings.json. If not then in keybindings.json.

A new override in settings.json can be a simple one-liner or a list:



// rest of configuration...
"vim.leader": "<Space>",
"vim.normalModeKeyBindingsNonRecursive": [
  { "before": ["<S-h>"], "commands": [":bprevious"] },
  { "before": ["<S-l>"], "commands": [":bnext"] },
],
// rest of configuration...

A new keybinding definition in keybindings.json usually looks like this:



// rest of configuration...
{
  "key": "ctrl+shift+q",
  "command": "workbench.action.closeWindow"
  // "when": " _condition for keybinding to be available_ "
},
// rest of configuration...

4. VSCodeVim configuration

Some of the most popular Vim settings do not require VSCodeVim, for example:



  "editor.lineNumbers": "relative",       // show relative line numbers
  "editor.cursorSurroundingLines": 8,     // scroll offset, number of lines
  "editor.suggest.insertMode": "replace", // what should happen on selecting a suggestion

Some are available only after plugin installation:



  "vim.leader": "<Space>",             // set Vim leader (key that indicates start of keybinding in Vim)
  "vim.hlsearch": true,                // show all matches of the most recent search
  "vim.inccommand": "replace",         // a behavior (visual feedback) of substitute command

The easiest way to find the setting is to start typing, a suggestion window should pop out and show all the related options. Alternatively, all the settings provided by VSCodeVim can be found in the official documentation under the "VSCodeVim settings" section.

Some settings, like those listed above can be declared as is, but keybindings declared in settings.json have to be defined per mode.



  "vim.visualModeKeyBindings": [
    { "before": ["<"], "commands": ["editor.action.outdentLines"] },
    { "before": [">"], "commands": ["editor.action.indentLines"] },
  ],

The definition above will allow to indent or remove indentation in visual mode.

Note!

If you are not familiar with the concept of modes in Vim, check this Wikibooks page.

Those are modes and list names that are available:

normal -> "vim.normalModeKeyBindings"
visual -> "vim.visualModeKeyBIndings"
insert -> "vim.insertModeKeyBindings"
operator pending mode -> "vim.operatorPendingModeKeyBindings"
normal, non recursive -> "vim.normalModeKeyBindingsNonRecursive"
visual, non recursive -> "vim.visualModeKeyBindingsNonRecursive"
insert, non recursive -> "vim.insertModeKeyBindingsNonRecursive"
operator pending mod, non recursive -> "vim.operatorPendingModeKeyBindingsNonRecursive"

Note!

If this is you first encounter with "operator pending mode" check this short article
The non recursive version helps, when you try to swap keys. Check key remapping section for more info and examples.

5. Getting rid of the mouse

The feeling of being forced to stop typing and reach for the mouse just to perform one click has to be one of the most infuriating. Therefore it is crucial to eliminate them as quickly as possible. Most important actions are:

Note!

In the code sections below, "before" can be changed to anything you want. Used keybindings are the ones I am using.

5.1 Focusing, switching and moving groups and tabs

The commands for switching between opened groups are:



// settings.json

{
  "before": ["leader", "h"],
  "commands": ["workbench.action.focusLeftGroup"]
},
{
  "before": ["leader", "j"],
  "commands": ["workbench.action.focusBelowGroup"]
},
{
  "before": ["leader", "k"],
  "commands": ["workbench.action.focusAboveGroup"]
},
{
  "before": ["leader", "l"],
  "commands": ["workbench.action.focusRightGroup"]
}
// VSCode has a command for switching between groups:
// { "key": "ctrl+1", "command": "workbench.action.focusFirstEditorGroup" }

The command ids for moving groups are:

"workbench.action.moveActiveEditorGroupLeft"
"workbench.action.moveActiveEditorGroupBelow"
"workbench.action.moveActiveEditorGroupAbove"
"workbench.action.moveActiveEditorGroupRight"
"workbench.action.moveEditorToFirstGroup"
"workbench.action.moveEditorToLastGroup"
"workbench.action.moveEditorToNextGroup"
"workbench.action.moveEditorToPreviousGroup"
"workbench.action.moveEditorLeftInGroup"
"workbench.action.moveEditorRightInGroup"

The commands for switching tabs are:



// settings.json

// switch between tabs:
{ "before": ["<S-h>"], "commands": ["workbench.action.nextEditor"] },
{ "before": ["<S-l>"], "commands": ["workbench.action.previousEditor"] },
// or Vim's ":bprevious" and ":bnext"

// switch between tabs in the same group:
{ "before": ["<S-h>"], "commands": ["workbench.action.nextEditorInGroup"] },
{ "before": ["<S-l>"], "commands": ["workbench.action.previousEditorInGroup"] },
// VSCode has a shortcut for opening a specific tab in group
// { "key": "alt+1", "command": "workbench.action.openEditorAtIndex1" }

Note!

Special pages like the visual version of settings.json prevent switching between tabs. Besides using openEditorAtIndex I have not yet found a way to override it.

5.2 Fixing problems

A typo, type mismatch or a missing import, this popup allows performing quick actions to fix most of the problems



{
    // keybindings.json
    "key": "ctrl+.",
    "command": "editor.action.quickFix",
    "when": "editorHasCodeActionsProvider && textInputFocus && !editorReadonly"
}

To limit quickFix action to only a normal mode, it could be moved to a settings.json file inside "workbench.action.moveEditorLeftInGroup: list, like so:



// settings.json
"vim.normalModeKeyBindings": [
  // ...
  {
    // "before": ...
    "commands": ["editor.action.quickFix"]
  }
  // ...
],

5.2 Cycling thru popup lists

Unfortunately VSCode uses multiple unrelated suggestion boxes that all require to be configured separately. For example, a "quick fix" window/widget/popup, displays multiple options but is not considered a "suggestWidgetMultipleSuggestions" and is in no way related with "quickOpen".

Note!

There is a good chance that my configuration is missing a popup window, but even after some heavy use I have yet to encounter one I would not be able to cycle through.
If you know a simpler way of configuring this or any other action please leave a comment.



{
  "key": "ctrl+n",
  "command": "selectNextSuggestion",
  "when": "editorTextFocus && suggestWidgetMultipleSuggestions && suggestWidgetVisible"
},
{
  "key": "ctrl+p",
  "command": "selectPrevSuggestion",
  "when": "editorTextFocus && suggestWidgetMultipleSuggestions && suggestWidgetVisible"
},
{
  "key": "ctrl+n",
  "command": "selectNextCodeAction",
  "when": "codeActionMenuVisible"
},
{
  "key": "ctrl+p",
  "command": "selectPrevCodeAction",
  "when": "codeActionMenuVisible"
},
{
  "key": "ctrl+n",
  "command": "workbench.action.quickOpenSelectNext",
  "when": "inQuickOpen"
},
{
  "key": "ctrl+p",
  "command": "workbench.action.quickOpenSelectPrevious",
  "when": "inQuickOpen"
}

By default an option can be selected using Enter or Tab key but additional shortcut can be added



{
    "key": "ctrl+y",
    "command": "acceptSelectedSuggestion"
    // or "command": "acceptSelectedCodeAction"
    // or "command": "workbench.action.acceptSelectedQuickOpenItem"
    // "when": ...
}

5.3 Scrolling popups

Sometimes the popups are longer or wider than the window they are displayed in. There is a popular trick that allows to perform a scroll without using a mouse:



{
  "key": "h",
  "command": "editor.action.scrollLeftHover",
  "when": "editorHoverFocused"
},
{
  "key": "j",
  "command": "editor.action.scrollDownHover",
  "when": "editorHoverFocused"
},
{
  "key": "k",
  "command": "editor.action.scrollUpHover",
  "when": "editorHoveredFocused"
},
{
  "key": "l",
  "command": "editor.action.scrollRightHover",
  "when": "editorHoverFocused"
}

5.4 Performing LSP actions

LSP actions are common tasks like checking the type of the variable, API definition or opening the implementation.



"vim.normalModeKeyBindingsNonRecursive": [
  // rest of keybindings...
  // Go to Definition
  { "before": ["g", "d"], "commands": ["editor.action.goToDefinition"] },
  // Peek Definition
  { "before": ["g", "p", "d"], "commands": ["editor.action.peekDefinition"] },
  // Show Hover
  { "before": ["g", "h"], "commands": ["editor.action.showDefinitionPreviewHover"] },
  // Go to Implementations
  { "before": ["g", "i"], "commands": ["editor.action.goToImplementation"] },
  // Peek Implementations
  { "before": ["g", "p", "i"], "commands": ["editor.action.peekImplementation"] },
  // Go to References
  { "before": ["g", "r"], "commands": ["editor.action.referenceSearch.trigger"] },
  // Go to Type Definition
  { "before": ["g", "t"], "commands": ["editor.action.goToTypeDefinition"] },
  // Peek Type Definition
  { "before": ["g", "p", "t"], "commands": ["editor.action.peekTypeDefinition"] },
  // rest of keybindings...
],

5.5 Search and replace

By default keybindings "ctrl+f" opens up "find widget" that allows searching in the current file. "ctrl+h" extends that functionality by ability to replace matches with provided value. The widget can be easily toggled with an extra "when condition" and the keybindings for "next match" and "previous match" can be overridden:



{
  "key": "ctrl+h",
  "command": "actions.find",
  "when": "editorFocus && editorIsOpen"
},
{
  "key": "ctrl+h",
  "command": "closeFindWidget",
  "when": "editorFocus && editorIsOpen && findWidgetVisible"
},
{
  "key": "ctrl+shift+h",
  "command": "editor.action.startFindReplaceAction",
  "when": "editorFocus && editorIsOpen"
},
{
  "key": "ctrl+n",
  "command": "editor.action.nextMatchFindAction",
  "when": "editorFocus && findWidgetVisible"
},
{
  "key": "ctrl+p",
  "command": "editor.action.previousMatchFindAction",
  "when": "editorFocus && findWidgetVisible"
},

6. Terminal

A quick access to a build in terminal will save a lot of time and mouse movement. The most important keybindings are:



{
  "key": "ctrl+shift+t",
  "command": "workbench.action.togglePanel"
},
{
  "key": "ctrl+shift+n",
  "command": "workbench.action.terminal.new",
  "when": "terminalIsOpen && terminalFocus"
},
{
  "key": "ctrl+n",
  "command": "workbench.action.terminal.focusNext",
  "when": "terminalIsOpen && terminalFocus"
},
{
  "key": "ctrl+p",
  "command": "workbench.action.terminal.focusPrevious",
  "when": "terminalIsOpen && terminalFocus"
},
{
  "key": "ctrl+q",
  "command": "workbench.action.terminal.kill",
  "when": "terminalIsOpen && terminalFocus"
},

7. Activity bar - treating activities like modes

Most of the time Explorer is the only activity view needed for work, but then the workflow is broken the moment non standard action like committing changes has to be made. With the already long list of custom keybindings and most short (two keys) combinations already taken, few options remain.

Instead of cramming new ones into "global scope" or adding a prerequisite of another shortcut, an activity view can be treated similarly to a Vim mode. For example, all actions related to file operations could be made accessible only when "Explorer" view is opened while actions related to Git, when "Source control view" is:



// EXPLORER
{
  "key": "ctrl+shift+e",
  "command": "workbench.view.explorer"
},
{
  "key": "n",
  "command": "explorer.newFile",
  "when": "filesExplorerFocus && !inputFocus"
},
{
  "key": "shift+n",
  "command": "explorer.newFolder",
  "when": "filesExplorerFocus && !inputFocus"
},
{
  "key": "x",
  "command": "filesExplorer.cut",
  "when": "filesExplorerFocus && !inputFocus"
},
{
  "key": "p",
  "command": "filesExplorer.paste",
  "when": "filesExplorerFocus && !inputFocus"
},
{
  "key": "d",
  "command": "deleteFile",
  "when": "filesExplorerFocus && !inputFocus"
},
// GIT
{
  "command": "workbench.view.scm",
  "key": "ctrl+shift+g"
},
{
  "key": "ctrl+s",
  "command": "git.stage",
  "when": "activeViewlet == 'workbench.view.scm' && sideBarFocus"
},
{
  "key": "ctrl+u",
  "command": "git.unstage",
  "when": "activeViewlet == 'workbench.view.scm' && sideBarFocus"
},
{
  "key": "ctrl+c",
  "command": "git.commitAllSigned",
  "when": "activeViewlet == 'workbench.view.scm' && sideBarFocus"
},
{
  "key": "ctrl+p",
  "command": "git.push",
  "when": "activeViewlet == 'workbench.view.scm' && sideBarFocus"
},

Condition used in code above should help override global scoped keybindings and give access to file and Git related keybindings only when the "File explorer" or "Source control" is the active and focus view. In the case of file explorer there is also a need to check if the user is not in the middle of inputting details.

Note!

Condition "filesExplorerFocus" works the same as "activeViewlet == 'workbench.view.explorer'", VSCodeVim just provides a simple shorthand.

8. Finding actions and conditions

The hardest part of configuring VSCodeVim is the sheer amount of IDs, names and available conditions. Besides looking online, the best option is playing around in the keyboard shortcut window. An action can usually be found by simply searching with a keyword.

The condition can be found by clicking on keybinding and selecting option "Change When Expression" (or using vi motions and shortcut) and trying different keywords. Some rules are obvious, some, like the ones related to widgets and popups, less so.
It is also worth testing different combinations with the use of "Record Keys" (button on the right side of the search bar) and copying shortcuts definitions.

9. Prettier and spellchecker

A lot of editing and fixing mistakes can be done automatically.
Prettier can be set either as a default or a language formatter and made to perform code formatting on save:



// settings.json
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,

// Settings appalled only when working with TypeScript
"[typescript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
},

"prettier.enable": true,

// Prettier configuration
"prettier.useTabs": true,

CodeSpellChecker works out of the box and allows correcting mistakes with the use of "quickFix" menu.

10. Closing thoughts

VSCode with the help of VSCodeVim and a lot of keybinding re-configuration is surprisingly comfortable and makes for a nice bridge into using Vim full time.

You can find my personal configuration here.

Thank you for reading and please leave a suggestion in the comments with your tips and tricks.

Sparse Checkout without command

Wojciech Rithaler — Mon, 27 Feb 2023 19:42:55 +0000

Although not well known, there is a way to achieve git sparse-checkout on git versions before 2.26.0.

Acknowledgments

This, slightly more in-depth article was made possible thanks to the one written by Brian Coyner on his blog.

Sparse checkout

Sparse checkout is git's functionality that lets users pull remote repositories partially, saving time and space. It works by changing the working tree from having all files tracked to only those specified.

Availability

Nowadays the functionality is available thru it's own command git sparse-checkout since version 2.26.0 and, although experimental, it is the recommended way.

Unfortunately there are times and situations, especially in large corporations where "newest" version of git are not available.

Fortunately there are ways of achieving sparse checkout in older git versions.

Creating sparse checkout manually step by step

Create new repository and add remote

   git init

Enable sparse checkout

   git config core.sparsecheckout true

This command enables the necessary sparse-checkout config settings

Specify directories To specify directories, edit file "sparse-checkout" inside directory .git/info by adding directory path per line, like so:

   dir-in-root
   another-dir-in-root/sub-dir

The "sparse-checkout" file uses the same syntax as ".gitignore" file, therefor it is possible to specify the unwonted directories with !, for example:

   !unwonted-dir-name

Add the remote To add remote, run:

   git remote add -f <name>

The -f flag will cause git to run git fetch <name> after remote information is set.

Pull files To pull files run:

   git pull <name> <branch>

The <name> must be the same name as the one provided in point 4.

Example

The example will use GitHub's git mirror to fetch directory "git/contrib/buildsystems" without it's subfolder "git/contrib/buildsystems/Generators".

git init
git config core.sparsecheckout true
echo contrib/buildsystems/* >> .git/info/sparse-checkout
echo !Generators >> .git/info/sparse-checkout
git remote add -f origin https://github.com/git/git.git
git pull origin master

After running each line separately and running them as a single script, the result of command ls -R example was:

./example:
contrib

./example/contrib:
buildsystems

./example/contrib/buildsystems:
CMakeLists.txt  Generators.pm  engine.pl  generate  parse.pl

Limitations

Git will not download actual files but will fetch information about the whole repo structure and tags.

There are ways of limiting what git will fetch:

--no-tags can be used to not download tags
--depth=<n> can be used to limit downloaded changes to to last "n" commits.

Adding or removing directory

Updating directories in "sparse-checkout" file will not automatically update local files. To update, a command git reset is required to be run like:

git reset --hard <remote-name>/<branch>

git reset resets the branch to specified state.

--hard changes all the files in working tree to match the files in specified state.

Running:

echo contrib/emacs/* >> .git/info/sparse-checkout
git reset --hard <remote-name>/<branch>

Resulted in:

example:
contrib

example/contrib:
buildsystems  emacs

example/contrib/buildsystems:
CMakeLists.txt  Generators.pm  engine.pl  generate  parse.pl

example/contrib/emacs:
README  git-blame.el  git.el

While manually removing the first line, end leaving "sparse-checkout" like:

!Generators
contrib/emacs/*

And running:

git reset --hard <remote-name>/<branch>

Resulted in:

example:
contrib

example/contrib:
emacs

example/contrib/emacs:
README  git-blame.el  git.el

Note!

I am not aware of any problems git reset may cause but it is a functionality I haven't fully tested for a meaningful amount of time.

The power of Remark

Wojciech Rithaler — Mon, 27 Feb 2023 18:49:57 +0000

1. Introduction

Markdown is an easy-to-learn versatile markup language. It can be transformed into HTML making it ideal for content-heavy sites that can be served statically. The transformation process can be done with many libraries. This post will describe how to use a library called Remark for cases where custom behavior may be required.

This article will go over:

process of installing and setting up the library
simple transformation of Markdown into HTML
creating custom plugins

Note!

A basic knowledge of writing scripts in Node.js and some knowledge about TypeScript are required!

2. Concepts and technologies

Before diving into the code, some concepts should be understood.

2.1. Markdown

Markdown is a markup language ideal for creating readable and editable text files. Since its creation, it has been widely used in blogs, documentation and even web pages.

2.2. Remark

Remark is the most popular JavaScript library (at least according to the authors) for transforming Markdown into HTML. It works by turning the content of a file into an abstract syntax tree, and with the help of plugins, changing its content.

3. Setting up the project

Demo application of this post will use Typescript. The necessary dependencies are:

Typescript
Remark
remark-html
unist-util-visit

Additionally, for the explanation and the ability to run and manually test the script, a single Markdown file with the name example.md, will be needed at the root of the directory:

    # Hello World 

    This is an example of Markdown content.

Note!

These were the commands that prepared the project and installed the necessary dependencies:

yarn init -y

yarn add typescript remark remark-html unist-util-visit

yarn add -D @types/mdast @types/node

yarn tsc --init More information about the process of setting up a Typescript project can be found in the official documentation. Remark is an ESM only package, more information on how to import it in TypeScript project can be found here.

4. Remark basics

This is the content of main.ts file, the place where the main part of the script will reside.

    import * as fs from 'fs'; 
    import remarkHtml from 'remark-html'; 
    import {remark} from 'remark'; 

    const mdToHtml = async (fileContent: string): Promise<string> => { 
        const result = await remark() 
            .use(remarkHtml, {sanitize: false}) 
            .process(fileContent); 

        console.log(result.toString()); 
        return result.toString(); 
    } 

    const content = fs.readFileSync('example.md', 'utf-8'); 
    mdToHtml(content);

The above code is the bare minimum that is required to transform Markdown. Every plugin can be applied the same way with the use of "use" function. Some plugins like the "remarkHtml" used in the code above, will allow passing additional parameters as a configuration. You can check this list of the most popular Remark plugins for reference.

When run, the result should look like the following:

    <h1>Hello World</h1> 
    <p>This is an example of Markdown content.</p>

5. About creating Remark plugins

Just transforming Markdown to HTML is easy and so is applying plugins, but, sometimes community-made ones may not solve all the problems. In those situations, a custom plugin can be written quite easily.

Note!

Reading this section about the concept of a plugin before going straight into coding is suggested.

There is of course an official tutorial on creating a plugin, but there are some problems with it:

it shows how to create a plugin for Unified (Unified is a "parent project", a collection of compatible plugins and a way to connect all sub-projects together. Which is mostly unnecessary when dealing with Markdown.)
it uses and focuses on Retext (another sub-project)
it shows a very basic example and uses a lot of functions from packages that have to be installed separately but are not needed
There is no example of an actual content manipulation

Note!

Even official documentation suggests using Remark sub-project when dealing with Markdown.

6. Creating a Remark plugin and analyzing AST

Let's finally dive into the code and create a separate file "customPlugin.ts" for a new plugin at the root of the project. Its content will look as follows:

    import { visit } from 'unist-util-visit';
    import { Root } from 'mdast';

    export default function customPlugin() {
        return (tree: Root) => { 
            visit(tree, (node) => { 
                console.log(node); 
            }); 
        } 
    }

For now, the only purpose of this plugin will be to display tree nodes. Of course, it has to be imported into the script and used with the "use" function like so:

    import customPlugin from './customPlugin.js';

    const mdToHtml = async (fileContent: string): Promise<string> => { 
        const result = await remark() 
            .use(remarkHtml, {sanitize: false}) 
            .use(customPlugin) 
            .process(fileContent); 

        console.log(result.toString()); 
        return result.toString(); 
    }

The output should look like this:

    { 
        type: 'root', 
        children: [ 
            { 
                type: 'heading', 
                depth: 1, 
                children: [Array], 
                position: [Object] 
            }, 
            { type: 'paragraph', children: [Array], position: [Object] } 
        ], 
        position: { 
            start: { line: 1, column: 1, offset: 0 }, 
            end: { line: 2, column: 42, offset: 56 } 
        } 
    } 
    { 
        type: 'heading', 
        depth: 1, 
        children: [ { type: 'text', value: 'Hello World', position: [Object] } ], 
        position: { 
            start: { line: 1, column: 1, offset: 0 }, 
            end: { line: 1, column: 14, offset: 13 } 
        } 
    } 
    { 
        type: 'text', 
        value: 'Hello World', 
        position: { 
            start: { line: 1, column: 3, offset: 2 }, 
            end: { line: 1, column: 14, offset: 13 } 
        } 
    } 
    { 
        type: 'paragraph', 
        children: [ 
            { 
                type: 'text', 
                value: 'This is an example of Markdown content.', 
            } 
        ], 
        position: { 
            start: { line: 2, column: 1, offset: 15 }, 
            end: { line: 2, column: 42, offset: 56 } 
        } 
    } 
    { 
        type: 'text',
        value: 'This is an example of Markdown content.', 
        position: { 
            start: { line: 2, column: 1, offset: 15 }, 
            end: { line: 2, column: 42, offset: 56 } 
        } 
    } 
    <h1>Hello World</h1> 
    <p>This is an example of Markdown content.</p>

That is a lot for just a heading and a paragraph, but it is logical. The script will always start with the "root" that contains all of the elements in the "children" array. Then it will move to the first child - in this case a heading, however, in reality, it consists of two objects: a parent tag and the text inside. That is why after printing a heading, the third printed object is a "text" node that contains the same text as the heading. The same situation happens with a fourth object - a paragraph, and its text is displayed as a fifth object. At the end there is of course the actual HTML, printed to the console from main.ts file.

7. Changing transformation of nodes - a simple example

The base for a plugin is ready, however, for now, it only prints the nodes as an object. To change that and better explain the process, in this example a hashtag ("#") will be added to all the headings.
Changing the way Remark will transform a node is as simple as changing an object's properties.

The function visit allows visiting only certain types of nodes. It can be specified as a second parameter with "heading" string. Now only heading nodes will be visited. Because of that visit can be used again inside to visit a text node. All elements of the tree can be visited with visit.

    import { visit } from 'unist-util-visit'; 
    import { Root, Heading } from 'mdast'; 
    import { Transformer } from 'unified';

    export default function customPlugin(): Transformer {
        return (tree) => { 
            visit(tree, 'heading', (node: Heading) => { 
                visit(node, 'text', (textNode) => { 
                    textNode.value = `# ${textNode.value}`; 
                }); 
            }); 
        } 
    }

Now this code will yield:

    <h1># Hello World</h1> 
    <p>This is an example of Markdown content.</p>

It is possible to visit many types of nodes. Instead of passing a string with type as a second parameter, a string array of types can be used.

8. Using Typescript

So far the examples shown were using Typescript passively for type checking, but there are situations where it can help with a lot more.

Markdown allows for adding HTML tags (example). Mixing syntax may seem unusual and is not recommended, but may occur with user-generated content. Not everyone uses Markdown daily.

Remark does not transform HTML markup but it can be done with some custom logic.

# Hello World 
This is an example of Markdown content. 

<img src="image.png" alt="HTML image">

The script result will now look like this:

    <h1># Hello World</h1> 
    <p>This is an example of Markdown content.</p> 
    <img src="image.png" alt="HTML image">

And this is how the image tag will look in AST:

{ 
  type: 'html', 
  value: '<img src="image.png" alt="HTML image">', 
  position: { 
    start: { line: 4, column: 1, offset: 60 }, 
    end: { line: 4, column: 39, offset: 98 } 
  } 
}

There is no distinction between tags. Any HTML syntax will be left untransformed and have type: 'html'.

This behaviour may cause trouble. For example when a domain has to be added to every image URL. The solution is a bit more custom logic.
First separate HTMLs with image tags from the rest by creating a Typescript interface:

interface HtmlImage extends HTML { 
    type: 'html'; 
    url: string; 
    alt: string; 
}

Check if value starts with <img. Type guard should be the best solution:

const isHtmlImage = (node: any): node is HtmlImage => {
    const HTML_IMG_SRC_REGEX = /src=["'](.+?)["']/i;
    const HTML_IMG_ALT_REGEX = /alt=["'](.+?)["']/i;

    if (node.type === "html" && node.value.startsWith("<img") && !node.value.includes(":")) {
        const url = HTML_IMG_SRC_REGEX.exec(node.value);
        const alt = HTML_IMG_ALT_REGEX.exec(node.value);
        node.url = url ? url[1] : "";
        node.alt = alt ? alt[1] : "";
        return true;
    } else return false;
}

An additional check should be made to filter out images from external resources.

Now to change image url, a simple if will be enough:

    if (isHtmlImage(node)) { 
        // node is of type HtmlImage and has keys "url" and "alt"  
        node.value = `<img src="-domain-${node.url}" alt="${node.alt}">` 
    }

9. Returning additional data

Sometimes users may forget to add an image or make a mistake in a path. Printing messages about all missing images may be useful:

    import * as fs from 'fs/promises'; 
    import remarkHtml from 'remark-html'; 
    import {remark} from 'remark'; 
    import customPlugin from './customPlugin.js';

    const mdToHtml = async (fileName: string): Promise<string> => { 
        const fileContent = await fs.readFileSync(fileName, 'utf-8'); 
        const result = await remark() 
            .use(remarkHtml, {sanitize: false}) 
            .use(customPlugin) 
            .process(fileContent);

        console.warn(`[WARNING] There are broken images in file ${fileName}. Image paths: ${result.data.missingPictures}`); 

        return result.toString(); 
    } 

    const fileName = "example.md"; 
    mdToHtml(fileName);

The custom plugin file:

    export default function customPlugin(): Transformer {
        return (tree, file: VFile) => {  
            const missingPicturesArray: string[] = []; 

            visit(tree, 'image', (node: Image) => { 
                if (!fs.existsSync(`./img/${node.url}`)) missingPicturesArray.push(`./img/${node.url}`);  
            });

            file.data['missingPictures'] = missingPicturesArray;
        } 
    }

The Markdown file:

# Hello World
This is an example of Markdown content.

![image](image.png)

This functionality is possible thanks to the fact that every Remark plugin returns a VFile. It’s an object containing information about provided Markdown file. The returned VFile object can be changed by adding things to its data sub-object.

Note!

Instead of providing just the content as a string in remark().process(content) a VFile object can also be used. Doing so may simplify passing parameters to plugins when dealing with more complex problems.

10. Async plugin / transformer

There are no examples of async plugin in the official documentation and almost none in articles.

A remark plugin can be asynchronous (Transformer returns Promise) but visit function is fully synchronous.

To overcome that a recursive function can be used:

import { Transformer } from 'unified';
import { HTML } from 'mdast';
import { Node, Parent } from 'unist';

import axios from 'axios';

async function asyncFunc() {
    const todo = await axios.get('https://jsonplaceholder.typicode.com/todos/1').then(result => {
        return result.data['title'];
    }).catch(error => {
        console.log(error);
    });

    return `todo response: ${todo}`;
}

async function asyncFuncTimeout() {
    const result = await new Promise((resolve) => {
        setTimeout(() => {
            resolve("setTimeout(5000) result");
        }, 5000);
    });

    return `timeout result: ${result}`;
}

function isHTML(node: Node): node is HTML {
    return node.type === "html";
}

async function mapNodes(node: Node | Parent<Node>, params: any): Promise<Node | Parent> {
    if (isHTML(node) && node.value.includes('async example')) node.value = await asyncFunc();
    if (isHTML(node) && node.value.includes('timeout example')) node.value = await asyncFuncTimeout();

    const childrenOrEmpty = (node as Parent).children || [];
    const children = await Promise.all( childrenOrEmpty?.map(childNode => mapNodes(childNode, params)) );

    return { ...node, children };
}

export default function asyncPlugin(params: any): Transformer {
    return async (tree) => await mapNodes(tree, params);
}

In above script, instead of using the visit function, a custom mapNode function was used. It's obvious problem is an assertion as Parent that is required.

After running the plugin on Markdown file with content:

# Hello World
This is an example of Markdown content.

<p>async example</p>

<p>timeout example</p>

The result was:

    <h1>Hello World</h1>
    <p>This is an example of Markdown content.</p>
    todo response: delectus aut autem
    timeout result: setTimeout(5000) result

11. Summary

Remark is a great ecosystem. It makes transforming Markdowns a breeze and simplifies adding features that would require way more time and effort.

What has been presented in this article is of course just a small subset of features and solutions, but it should be more than enough for a seamless start with the technology.

I would like to thank my supervisor Tomasz Dyła for providing guidance on this article.

Thank you very much for reading and let me know in the comments if you have any suggestions.