vim-markdown-runner and a Notes Based Workflow
I recently wrote a simple vim plugin, vim-markdown-runner, to complement my markdown notes based project workflow. In this post I want to go into a few more details on this workflow and show how its simplicity is surprisingly powerful.
Overall Structure
I store all of my note files in a single root directory in Dropbox. This allows me to easily view and edit the notes from a mobile device. This root directory structure mirrors my home directory, which allows me to associate project file paths with their note file. For instance if I have a project in ~/projects/side-projects/my-project the associated note file is located at ~/Dropbox/notes/projects/side-projects/my-project.md.
I then create a symlink .notefile in the original project folder that points to the full Dropbox based path. The reason for creating the symlink is twofold: (i) to allow for quick viewing of a file from within the project directory, and (ii) so that when editing a file vim remains in the project folder, so things like ctrlp searching still work as expected (instead of accidentally searching the notes folder).
I added a few functions and a :Notes command to my .vimrc to create or open the associated note file for my current working directory.
Notes() does the heavy lifting. If a .notefile is already present it simply opens it. If there is not a .notefile it runs NotesInitNew() which checks if the associated Dropbox file exists. If the file doesn’t exist in Dropbox yet it creates the correct directory structure, then creates a new markdown file already populated with a title based on the final directory name. Finally, the .notefile symlink is created, then opened.
Inside a Note File
Inside a typical note file I’ll have the usual lists of todos, random meeting notes and other routine items, but the true power comes from vim-markdown-runner which allows me to have interactive playgrounds, project specific scripts, and a basic API client detailing a projects routes, replacing Postman or Paw.
Playgrounds
During development I am often troubleshooting or verifying a small piece of code, having a simple playground greatly facilitates this.
## Playground```go
fmt.Println(os.Getwd())
``````python
import pandas as pd
print(pd.read_csv('data.csv'))
```
With vim-markdown-runner I can place my cursor in either of those code blocks and execute them. The correct language/environment will be automatically detected, and in the case of Go some additional steps are performed to add a main() and run goimports.
Scripts
I will often have project specific scripts that are not really worth putting in their own files. I can run those with vim-markdown-runner as well:
## Scripts```
get_name() {
echo "Dan"
}echo "You are $(get_name)"
```
If no language is specified in the code block vim-markdown-runner will run it with whatever $SHELL is set to.
API Client
Within web development projects I have an Endpoints section in my note file, as a simple replacement for Postman and the like. These are just httpie commands, but it allows me to easily catalog and re-run common routes:
## Endpoints```
http localhost:3000/api/todos
``````
http POST localhost:3000/api/todos title=Stuff
```...etc
As you can see there are a variety of powerful use cases that vim-markdown-runner handles. It is also very configurable, so you should be able to adjust it to your own needs.
