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.
I can see that the author shares the best distraction-free writing
environment he realized by tweaking plugins and configuration, which
works for himself/herself. Which is awesome.
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.
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.
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:
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.)
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
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.
which lets me type "simplenote" at the command line and get a vim editor that is open on my Simplenote account. Then I markdown away and can preview/publish from the web interface!
« 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>
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 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.
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.
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.
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?
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).
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.
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?
> 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.
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:
nnoremap g gj
nnoremap k gk
That's it, once and done. Aside from setting your wrap preferences—which you would have had to do anyway with hard wraps—there's no more to be taken care of. The text will always display fluently and in full, and you will have no need to manually reformat your paragraphs using gqap whenever you make a change to them. All that need concern you is the text, not its line-by-line arrangement.
(I do agree that vim-pencil is unnecessary, at least if you're only going to use one scheme for wrapping.)
35 comments
[ 2.6 ms ] story [ 66.6 ms ] threadBut also I want to try it.
That's a great setup for my blog postings that I already write in markdown.
Hope it helps :)
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.
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.
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
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.)
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:
which lets me type "simplenote" at the command line and get a vim editor that is open on my Simplenote account. Then I markdown away and can preview/publish from the web interface!<joke>So, it's not a very efficient distraction-free setup...</joke>
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.
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.
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.)
* 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
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
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.
This solution, meanwhile, is far from inelegant:
That's it, once and done. Aside from setting your wrap preferences—which you would have had to do anyway with hard wraps—there's no more to be taken care of. The text will always display fluently and in full, and you will have no need to manually reformat your paragraphs using gqap whenever you make a change to them. All that need concern you is the text, not its line-by-line arrangement.(I do agree that vim-pencil is unnecessary, at least if you're only going to use one scheme for wrapping.)