journal.vimgist.2018-11-21.md

Journaling with vim and Gist

2018-11-21

The Requirements

I have been been searching for a way to keep a developer journal. Here are my requirements:

1. Supports vim on laptop/desktop
2. Supports GitHub-style Markdown
3. Persists somewhere in the internet, so I can fetch from anywhere
4. Replaces my use of Google Keep on my Android phone (nice-to-have)

I have tried GitBook and JotterPad. GitBook meets all of the requirements except for 4, but it's web UI is klunky and seemed overkill for what I needed. JotterPad meets only 2 and 4 I wanted something lightweight that allowed me to edit in vim and easily sync to Gist.

gist-vim

I finally used the right Google search term for what I was wanting ("vim sync gist") and found gist-vim which allows you to save the current vim buffer to Gist with (using the default privacy setting):

:Gist

Then, add the *.md extension for Markdown rendering in Gist (have to do this after posting to Gist):

:Gist -e myjournal.md

Setup

I set my runtimepath manually (trying to minimize my vim dependencies). Here are the steps I took to get this working:

1. git clone [email protected]:mattn/webapi-vim.git ~/.vim/bundle/webapi-vim
2. git clone [email protected]:mattn/gist-vim.git ~/.vim/bundle/gist-vim
3. Add the following lines to .vimrc:

set runtimepath^=~/.vim/bundle/webapi-vim
set runtimepath^=~/.vim/bundle/gist-vim

4. git config --global github.user <username> (this is optional if you only want to create anonymous gists)
5. vim
6. Type 'test'
7. :Gist
8. Enter your GitHub password and 2-factor code if you have that enabled
9. Your buffer will be saved to Gist
10. :Gist -b will open your Gist in your default browser

Caveats

Here are some caveats I noticed about this solution:

• If you save with :w often like I do, you might find typing :Gist to save annoying. The documentation says, "You can update the gist with the ':w' command within the gist buffer," after using Gist -e, but it doesn't work for me (see my question here)
• Although the GitHub password is not stored, this does create a GitHub OAuth access token for gist API calls.

Conclusion

Despite these concerns, this solution met the requirements above and is more lightweight than the other stuff I tried.

Update 2019-06-25

I will write a sequel to this post about my use of mdp and gist for presentations from vim and persisting in gist. I am currently running this in vim:

:!gist -r ad5b32e9d5e0f29cc735e2ffade15e7b | mdp

Other resources to look into 2019-06-25

• https://nickjanetakis.com/blog/writing-and-previewing-markdown-in-real-time-with-vim-8
• https://jdhao.github.io/2019/01/15/markdown_edit_preview_nvim/
• https://vi.stackexchange.com/a/8537/16026
• https://medium.com/@andymcfee/how-to-import-markdown-into-medium-c06dc981bd96

GistID: 30c894048190999761d2033ff7eb1edc