This repository has been archived by the owner on Mar 5, 2019. It is now read-only.
/
markdown-preview.txt
198 lines (152 loc) · 8.63 KB
/
markdown-preview.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
*markdown-preview.txt*
Author:
Matthew Kitt <github.com/mkitt>
This plugin is licensed under the terms of the MIT License. Please see
markdown-preview.vim for the license in its entirety. For license info
around the redcarpet or discount parser see:
https://github.com/tanoku/redcarpet/blob/master/COPYING
https://github.com/Orc/discount/blob/master/COPYRIGHT
==============================================================================
Markdown Preview *markdown-preview*
1. Introduction |markdown-preview-intro|
2. Dependencies |markdown-preview-dependencies|
3. Parser Settings |markdown-preview-parsers|
4. Usage |markdown-preview-usage|
5. Options |markdown-preview-options|
Temporary File Directory |markdown-preview-tmpdir|
Default Styles |markdown-preview-defaultstyles|
User Styles |markdown-preview-userstyles|
Default Theme |markdown-preview-defaulttheme|
Always Open |markdown-preview-alwaysopen|
6. Themes |markdown-preview-themes|
7. Workflow |markdown-preview-workflow|
==============================================================================
1. Introduction *markdown-preview-intro*
Markdown Preview allows you to compile and preview markdown as generated HTML
files. It has the ability to select and use customized stylesheets for
previewing your own awesomeness. Previewing occurs within the default browser.
==============================================================================
2. Dependencies *markdown-preview-dependencies*
Markdown Preview requires the following:
- Vim version 7.0 or above with Ruby support
Either:
- Redcarpet - The default parser to use if it's installed
gem install redcarpet
- Discount - The backup parser to use if redcarpet is not found
brew install discount
The plugin first tests if Redcarpet is installed, if so it will use it
as it's parser, otherwise it will check for Discount and rock that. If
neither parser is installed, then the plugin shuts down silently.
While not a requirement, default directories are tailored to work within a
bundle directory as specified by the pathogen plugin.
Currently tested to work with MacVim and Vim from Terminal.
==============================================================================
3. Parser Settings *markdown-parsers*
The following settings are what either Redcarpet or Discount run with
Redcarpet:
- autolink
- no_intra_emphasis
- tables
- fenced_code_blocks
- lax_html_blocks
- strikethrough
- superscript
- space_after_headers
Discount:
- +autolink
==============================================================================
4. Usage *markdown-preview-usage*
Send Vim the command :MDP within a markdown file and it will convert and
generate a temporary HTML file. You probably want to map this command to a
leader shortcut: map <leader>p :MDP<CR>.
Send Vim the command :CMDP within a markdown file and it will clear out
all the temporary files that have been generated. These are automatically
cleaned up every time you launch your vim editor.
See also below for workflow suggestions.
==============================================================================
5. Options *markdown-preview-options*
Markdown Preview comes configured with a few global variables which can be
overridden within you .vimrc file.
g:MarkdownPreviewTMP *markdown-preview-tmpdir*
This is the directory where the temporary HTML files are saved after being
generated. These are cleaned out every time you relaunch Vim. The default
setting is ~/.vim/bundle/markdown-preview.vim/tmp/. To override this location:
let g:MarkdownPreviewTMP = $HOME.'/.vim/tmp/'
g:MarkdownPreviewDefaultStyles *markdown-preview-defaultstyles*
This is the directory where default style themes live. At the moment 2 are
included with this plugin: github, readable. The default setting is at
~/.vim/bundle/markdown-preview.vim/stylesheets/. To override this location:
let g:MarkdownPreviewDefaultStyles = $HOME.'/.vim/stylesheets/'
Setting up themes is explained in more detail below.
g:MarkdownPreviewUserStyles *markdown-preview-userstyles*
This is the directory where user style themes live. This is something
you would want to define in your .vimrc file as it's included to allow
a customized set of themes for various uses. For simplicity, it will
default to whatever the g:MarkdownPreviewTMP directory is and will not
show any user styles within the select options.
let g:MarkdownPreviewUserStyles = ~/Sites/themes/markdown/
Setting up themes is explained in more detail below.
g:MarkdownPreviewDefaultTheme *markdown-preview-defaulttheme*
The default theme converted markdown themes will start with after they
are generated for the first time. Defaults to github which is bundled
with the default styles. To override:
let g:MarkdownPreviewDefaultTheme = 'readable'
g:MarkdownPreviewAlwaysOpen *markdown-preview-alwaysopen*
By default Markdown Preview will only open the browser window the first
time you generate a file. After that, it will generate the file, but not
open the browser window. See the workflow section below for more information.
To override this setting and have the browser window open everytime set the
following in your .vimrc file:
let g:MarkdownPreviewAlwaysOpen = 1
==============================================================================
6. Themes *markdown-preview-themes*
Markdown Previews can be themed with different CSS stylesheets. Included are
2 default themes which can be used for reference when creating user specific
themes. The User directory should be setup similar to the default styles in:
~/.vim/bundle/markdown-preview.vim/stylesheets/
There are a few rules for setting User themes up.
Included in the global variables are an option for setting a location to where
the User themes live. Set those up in your .vimrc file first like so:
let g:MarkdownPreviewUserStyles = ~/Sites/themes/markdown/
Then within your theme directory create additional directories for each theme
you might generate. For each of those themes you'll need to create a style.css
file and optionally a print.css file (you can also create an images or support
folder in there as well if thats what you need). So for example, your User theme
directory should look like this:
-Sites
| - themes
| | - markdown
| | | - snowblind
| | | | - style.css
| | | | - print.css
| | | | - images
| | | | | - bg.png
| | | + my-other-theme
Use one of the default themes as a starting point. You'll need to make sure
your user styles are namespaced to whatever theme you've named the parent
directory. Once complete, you should see your themes in the select menu within
the header.
==============================================================================
7. Workflow *markdown-preview-workflow*
A couple of notes about workflow, what has worked for me, and why some settings
are the way they are.
In my .vimrc file, I listen for a BufWritePost on markdown files and
call the command :MDP to convert the file. If the file hasn't been
generated it will open your default browser to the html file. The second
time I save, the files is converted but a new window is not open based
on the default setting of g:MarkdownPreviewAlwaysOpen=0. In my workflow,
I've left the browser window open and just have to refresh that page to
see any changes to the markdown file.
The only drawback from this setting is if I happen to close the browser window,
the plugin has no way of knowing this and won't open a window the next time
you generate :MDP for that file. You basically have to either navigate to the
temp file from your history or call the command :CMDP and run :MDP again.
You can always override this behavior by setting:
let g:MarkdownPreviewAlwaysOpen = 1
With this set, a system.open is called every time the :MDP command is issued.
This has negative effects within some browsers as it keeps generating new
windows. While not a big deal, if you are using a theme that is not your
default, you'll have to continually select the theme you are looking for.
Cookies on files within the file system do not actually work.
==============================================================================
vim:tw=78:ts=8:ft=help:norl: