Vim setup for Markdown(swamphogg.com)
swamphogg.com
Vim setup for Markdown
http://www.swamphogg.com/2015/vim-setup/
13 comments
I fully agree.
It's easy to spend hours tweaking the perfect setup, but it's a never ending task. Also the more you tweak it the easier it breaks at each upgrade, and the more you rely on it and miss it when you're not on your personal computer. For this reason I'm reluctant to add mappings such as inoremap jk <Esc> to my .vimrc for fear of getting used to it.
It's easy to spend hours tweaking the perfect setup, but it's a never ending task. Also the more you tweak it the easier it breaks at each upgrade, and the more you rely on it and miss it when you're not on your personal computer. For this reason I'm reluctant to add mappings such as inoremap jk <Esc> to my .vimrc for fear of getting used to it.
"It's good enough for me so why change it."
That's basically your age-old argument, which is fine. However, there's nothing wrong with other people optimizing their productivity even further. Personally, I appreciate people who try to tune their editing. It should be a more precise task with less effort. I don't use vim much these days but people are doing a great job in promoting precision:
http://vimgolf.com
Vim - precision editing at the speed of thought https://vimeo.com/53144573
That's basically your age-old argument, which is fine. However, there's nothing wrong with other people optimizing their productivity even further. Personally, I appreciate people who try to tune their editing. It should be a more precise task with less effort. I don't use vim much these days but people are doing a great job in promoting precision:
http://vimgolf.com
Vim - precision editing at the speed of thought https://vimeo.com/53144573
I understand your sentiment. When it comes to coding, I pay attention to productivity because coding involves so many various tasks and cognitive switches that cause friction and block progress.
But writing, for me, is different. My primary progress blocker for writing is not writing. And spending time tweaking technology is so tempting, and so fun, and very much not writing.
I am, in fact, doing right now not writing, so I should get back to it. (Plain MacVim, using Latex as the markup.)
But writing, for me, is different. My primary progress blocker for writing is not writing. And spending time tweaking technology is so tempting, and so fun, and very much not writing.
I am, in fact, doing right now not writing, so I should get back to it. (Plain MacVim, using Latex as the markup.)
How often do you have to switch off your main computer? Depending on the frequency and length of your stay on a foreign computer, putting your vim files (including vimrc, set of plugins and custom snippet files) in a github repo might be wise. Then you can get up and running with the same vim environment anywhere that has git installed. Here's mine, for example: https://github.com/tristanpendergrass/.vim
Part of the beauty of Markdown is that you don't have to use soft wrapping. Consecutive lines (with no empty lines in between) are combined into paragraphs.
I put every sentence (or longer clause) on its own line. This keeps the navigation paradigm the same. And more importantly, diffs are still readable. If you're doing any kind of collaboration or revision with your Markdown documents, trying to read diffs with one change in the middle of a paragraph-long line is quite frustrating.
I put every sentence (or longer clause) on its own line. This keeps the navigation paradigm the same. And more importantly, diffs are still readable. If you're doing any kind of collaboration or revision with your Markdown documents, trying to read diffs with one change in the middle of a paragraph-long line is quite frustrating.
I hadn't considered this approach. It seems potent for revision history, but frustrating for reading and review within the source files, or do have vim configuration aids to html/markdown wrap and navigation?
Yeah, I suppose reading a bunch of one-sentence-per-line paragraphs might be a bit sub-optimal, but I haven't found it to be a problem in practice. For longer documents, it's not much trouble to read the rendered version and do edits in the source.
All very good suggestions, especially Goyo for distraction-free writing.
I personally enjoy vim-livedown:
https://github.com/shime/vim-livedown
It opens up a browser window with a rendered Markdown page, and live updates when a Markdown file changes. This lets you do "split screen text/preview" editing, which is wonderful.
I also enjoy the simplenote.vim plugin. Simplenote is the hosted note taking service run by the team at Automattic/Wordpress. It's not well known that it supports Markdown fully, and also has a way to one-click publish your Markdown posts. The vim plugin lets you edit all your Simplenotes inside vim itself! If you use Simplenote, this is a great plugin.
https://github.com/mrtazz/simplenote.vim
I also set up a bash alias like this:
I personally enjoy vim-livedown:
https://github.com/shime/vim-livedown
It opens up a browser window with a rendered Markdown page, and live updates when a Markdown file changes. This lets you do "split screen text/preview" editing, which is wonderful.
I also enjoy the simplenote.vim plugin. Simplenote is the hosted note taking service run by the team at Automattic/Wordpress. It's not well known that it supports Markdown fully, and also has a way to one-click publish your Markdown posts. The vim plugin lets you edit all your Simplenotes inside vim itself! If you use Simplenote, this is a great plugin.
https://github.com/mrtazz/simplenote.vim
I also set up a bash alias like this:
alias simplenote=vim -c "Simplenote -l"
« As of today, I’ve been using this setup for, err, about 9 months. I started writing this in December last year but never got around to finishing the post. »
<joke>So, it's not a very efficient distraction-free setup...</joke>
<joke>So, it's not a very efficient distraction-free setup...</joke>
As somone who doesn't like to configure and tweak stuff for hours, my favorite Markdown editor is VS Code. You only have to set "editor.wrappingColumn" to zero (viewport wrapping) and you're good to go.
You can use tables, fenced code blocks (there is syntax highlighting too), and images (I use viewBox'd SVGs for my diagrams). And of course there is the usual split view and a live preview on whichever side you prefer. You can also customize the CSS if you want, but the default one looks fine, really.
It does everything I need from a Markdown editor out of the box.
https://code.visualstudio.com/Docs/languages/markdown
(The right sidebar can be toggled with Ctrl+B.)
You can use tables, fenced code blocks (there is syntax highlighting too), and images (I use viewBox'd SVGs for my diagrams). And of course there is the usual split view and a live preview on whichever side you prefer. You can also customize the CSS if you want, but the default one looks fine, really.
It does everything I need from a Markdown editor out of the box.
https://code.visualstudio.com/Docs/languages/markdown
(The right sidebar can be toggled with Ctrl+B.)
Good information on Microsoft Visual Studio support of markdown. Your lead in of my time is precious is a little disappointing, because everyone's time is precious. Do you do other productivity hacks like home row navigation? How much time do you spend in markdown? Do you find the highlighting and rendering 100% consistent with github or is your target something else? Is it following the commonmark spec? How does it handle highlighting complex (nested) character formatting? When there is a bug, is it easy to report? How responsive are they? Can you fix it yourself?
https://github.com/vim-pandoc/vim-pandoc is far superior.
What makes it better? The README doesn't really tell me what it does either.
Far superior to what? In what way?
Slightly unrelated, but I'm currently migrating my company's main documentation (we are an entreprise software shop) from a bunch of unversioned docx to a central git repo hosting a markdown files that gets glued together into a unique PDF, thanks to pandoc.
Vim is the icing on the cake here: writing documentation becomes less painful with a distraction-free modal text editor compared to a bloated Word.
Vim is the icing on the cake here: writing documentation becomes less painful with a distraction-free modal text editor compared to a bloated Word.
A bit unrelated, but I really don't get the idea of "distraction free" editing for documentation. When I write documentation, it's always side-by-side with existing specs, a codebase or a demo. I never really feel the need to disconnect from what I'm documenting.
People use markdown for more than documentation - I use a very similar setup to the OP's for journaling, where I definitely do want to disconnect.
> I could fix it up by re-mapping ‘j’ to ‘gj’ and ‘k’ to gk’ but vim-pencil does all that and probably more for you.
Have you considered just using hard wrapping instead? Sometimes having a problem solving mindset can make one miss the more elegant solution. Since you said you don't have a strong opinion in regards to hard vs. soft wrapping, why go through the trouble of fixing an issue when you could simply make the issue irrelevant?
At this point you've already got it solved so it's a bit of a moot point, but I'm interested in your thought process here.
Have you considered just using hard wrapping instead? Sometimes having a problem solving mindset can make one miss the more elegant solution. Since you said you don't have a strong opinion in regards to hard vs. soft wrapping, why go through the trouble of fixing an issue when you could simply make the issue irrelevant?
At this point you've already got it solved so it's a bit of a moot point, but I'm interested in your thought process here.
Hard wrapping may be an elegant solution on the runtime configuration side, but it is frequently to blame for inelegance when editing. Hard-wrapped text must be manually reformatted for display when (1) changing terminal or window size, (2) vertically splitting panes, (3) opening a file on a different monitor. Hard-wrapped text must also be manually reformatted after many editing tasks: new lines, far shorter in length than the textwidth of the paragraph as a whole, sit in the middle of old ones that wrapped naturally, while some old lines teeter out into your wrap margin (and off of your display) after text was inserted into their middles.
This solution, meanwhile, is far from inelegant:
(I do agree that vim-pencil is unnecessary, at least if you're only going to use one scheme for wrapping.)
This solution, meanwhile, is far from inelegant:
nnoremap g gj
nnoremap k gk
(I do agree that vim-pencil is unnecessary, at least if you're only going to use one scheme for wrapping.)
[deleted]
I personally use (and I'm very happy):
https://github.com/gabrielelana/vim-markdown
Hope it helps :)
Hope it helps :)
Updating project documentation is often my first opportunity to contribute to an open source project. Most use hard returns but a high enough precentage use soft returns that my long line highlighting and navigation is frustrating. Has anyone setup vim to switch configurations between these sort of formatting details?
Not an OSX user, so maybe someone can explain: why launch Tmux just to launch Vim rather than launching Vim natively in iTerm?
Here are some of my reasons for running tmux inside of iTerm:
* easy layout of panes (windows) in fullscreen mode. I have tmux macros setup to quickly get different pane layouts -- e.g. 65% left, then two vertical split panes in the remaining right 35%. Typically I run vim in the larger pane and then have two other panes for various other CLI stuff on dev systems. I have a number of other preconfigured layouts depending on what I'm trying to get done.
* tmux session can be detached/reattached. I've on occasion had iTerm crash or I've accidentally quit it (cmd-Q). With tmux, my session is still running, so I just restart iTerm and reattach...everything back where I left off. There is even a new-ish plugin for tmux that lets you save tmux sessions so that you can restore after restart. The reattaching also makes it low-overhead if/when iterm wants to update itself (admittedly rare).
* Once you get used to tmux navigation keys/commands, they will conceptually work on linux systems as well if you run tmux (more portable muscle memory).
just my $0.02
* easy layout of panes (windows) in fullscreen mode. I have tmux macros setup to quickly get different pane layouts -- e.g. 65% left, then two vertical split panes in the remaining right 35%. Typically I run vim in the larger pane and then have two other panes for various other CLI stuff on dev systems. I have a number of other preconfigured layouts depending on what I'm trying to get done.
* tmux session can be detached/reattached. I've on occasion had iTerm crash or I've accidentally quit it (cmd-Q). With tmux, my session is still running, so I just restart iTerm and reattach...everything back where I left off. There is even a new-ish plugin for tmux that lets you save tmux sessions so that you can restore after restart. The reattaching also makes it low-overhead if/when iterm wants to update itself (admittedly rare).
* Once you get used to tmux navigation keys/commands, they will conceptually work on linux systems as well if you run tmux (more portable muscle memory).
just my $0.02
If someone is launching only Vim from tmux, it possibly is an overkill.
I have stayed put with Vim, Tmux and shell, a very capable triumvirate. It allows one to build your own IDE.
Especially when your project may need some customization beyond an IDE.
Ex: I work on a python application which needs to support 4 different library versions (python wrapper over C++) and I have 4 venvs, for each version. I have a tmux session, with a pane for each venv, one vim, one tail etc. I tried for ex: PyCharm and every time I do python setup.py develop in each venv, there goes the IDE with all it's scanning stuff.
Tmux just lets me do what I want without getting in the way. And tmux-resurrect is a great addition. [1] [1]: https://news.ycombinator.com/item?id=10219003
I have stayed put with Vim, Tmux and shell, a very capable triumvirate. It allows one to build your own IDE.
Especially when your project may need some customization beyond an IDE.
Ex: I work on a python application which needs to support 4 different library versions (python wrapper over C++) and I have 4 venvs, for each version. I have a tmux session, with a pane for each venv, one vim, one tail etc. I tried for ex: PyCharm and every time I do python setup.py develop in each venv, there goes the IDE with all it's scanning stuff.
Tmux just lets me do what I want without getting in the way. And tmux-resurrect is a great addition. [1] [1]: https://news.ycombinator.com/item?id=10219003
I had the same question too. tmux is great when you don't have iterm available. You can split your terminal out into new sessions in iterm.
Well, tmux gives you a bit of features if you have to do anything else other than editing a file (ie: connecting via ssh)
vim for everything!
That's a great setup for my blog postings that I already write in markdown.
That's a great setup for my blog postings that I already write in markdown.
However, it should be noted that Vim already is a distraction-free writing environment, and Markdown is quite simple enough. A vanilla Vim with Markdown highlighting is actually enough. In fact, as long as being "distraction-free" is concerned, just VI should be enough.
Althought I am all for tweaking, I always keep in mind that sometimes I am better off tweaking the writing itself, rather than the tools.
I am sharing this because sometimes we tend to get lost in configuration, and we need reminders to get out.