vim-instant-markdown.txt

*vim-instant-markdown.txt* - Last change: 2022-01-14
*vim-instant-markdown*
*instant-markdown*

================================================================================
CONTENTS                                           *vim-instant-markdown-contents*

1. Introduction...............................|vim-instant-markdown-introduction|
2. Installation...............................|vim-instant-markdown-installation|
   2.1 One shot installation of instant-markdown-d........|:InstantMarkdownDPath|
3. Configuration.............................|vim-instant-markdown-configuration|
   3.1. g:instant_markdown_slow.........................|g:instant_markdown_slow|
   3.2. g:instant_markdown_autostart...............|g:instant_markdown_autostart|
        Manual start....................................|:InstantMarkdownPreview|
        Manual stop........................................|:InstantMarkdownStop|
   3.3. g:instant_markdown_open_to_the_world.|g:instant_markdown_open_to_the_world|
   3.4. g:instant_markdown_allow_unsafe_content.|g:instant_markdown_allow_unsafe_content|
   3.5. g:instant_markdown_allow_external_content.|g:instant_markdown_allow_external_content|
   3.6. g:instant_markdown_logfile...................|g:instant_markdown_logfile|
   3.7. g:instant_markdown_mathjax...................|g:instant_markdown_mathjax|
   3.8. g:instant_markdown_mermaid...................|g:instant_markdown_mermaid|
   3.9. g:instant_markdown_browser...................|g:instant_markdown_browser|
   3.10. g:instant_markdown_port........................|g:instant_markdown_port|
   3.11. g:instant_markdown_autoscroll............|g:instant_markdown_autoscroll|
   3.12. g:instant_markdown_theme......................|g:instant_markdown_theme|
4. Tips and tricks.........................|vim-instant-markdown-tips-and-tricks|

================================================================================
1. INTRODUCTION                               *vim-instant-markdown-introduction*

Want to instantly preview finicky markdown files, but don't want to leave your
favourite editor, or have to do it in some crappy browser text area?
vim-instant-markdown is your friend! When you open a markdown file in vim, a
browser window will open which shows the compiled markdown in real-time, and
closes once you close the file in vim.

As a bonus, github-flavored-markdown
(http://github.github.com/github-flavored-markdown/) is supported, and styles
used while previewing are the same as those GitHub uses!

--------------------------------------------------------------------------------
2. INSTALLATION                               *vim-instant-markdown-installation*

Quick start (assuming you have all the necessary dependencies):

*   Install the Node.js mini-server by running either:
>
      [sudo] npm -g install instant-markdown-d
<
    or, for the pre-release version:
>
      [sudo] npm -g install instant-markdown-d@next
<
    alternatively for the Python mini-server :
>
      pip install --user smdv
<

*   Add the following to your `.vimrc`, depending on the plugin manager of your
    choice:
    *   vim-plug (https://github.com/junegunn/vim-plug)
>
            Plug 'instant-markdown/vim-instant-markdown', {'for': 'markdown'}
<
    *   Vundle (https://github.com/gmarik/Vundle.vim)
>
            Plugin 'instant-markdown/vim-instant-markdown'
<
    *   Vim8 built-in package manager (Execute the following command instead of adding it to `.vimrc`)
>
           # NOTE:
           # 1. Please check you have git installed.
           # 2. Please replace * with a package name you want.
           git clone https://github.com/instant-markdown/vim-instant-markdown.git ~/.vim/pack/*/start/
<

Detailed instructions

-   If you're on Linux, ensure the following packages are installed:
    -   `xdg-utils`
    -   `curl`
    -   `nodejs-legacy` (for Debian-based systems)
-   If you're on Windows, you will need into install cURL
    (<http://curl.haxx.se/download.html>) and put it on your `%PATH%`.
-   If you do not use a plugin manager, copy the
    `ftplugin/markdown/instant-markdown.vim`
    (ftplugin/markdown/instant-markdown.vim) file into
    `~/.vim/ftplugin/markdown/` (creating directories as
    necessary),
-   Open a markdown file in vim and enjoy!

------------------------------------------------------------------------------
2.1 ONE SHOT INSTALLATION OF INSTANT-MARKDOWN-D       *:InstantMarkdownDPath*

The server *instant-markdown-d* can also be installed using vim-plug
as:
>
   Plug 'suan/vim-instant-markdown', {'for': 'markdown', 'do': 'yarn install'}
<
The command resolves the path to instant-markdown-d path. This is useful if
the tool is installed locally along with the plugin directory.

--------------------------------------------------------------------------------
3. CONFIGURATION                            *vim-instant-markdown-configuration*

Minimal default configuration:

>
        filetype plugin on
        "Uncomment to override defaults:
        "let g:instant_markdown_slow = 1
        "let g:instant_markdown_autostart = 0
        "let g:instant_markdown_open_to_the_world = 1
        "let g:instant_markdown_allow_unsafe_content = 1
        "let g:instant_markdown_allow_external_content = 0
        "let g:instant_markdown_mathjax = 1
        "let g:instant_markdown_mermaid = 1
        "let g:instant_markdown_logfile = '/tmp/instant_markdown.log'
        "let g:instant_markdown_autoscroll = 0
        "let g:instant_markdown_port = 8888
        "let g:instant_markdown_python = 1
<
------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_SLOW                                *g:instant_markdown_slow*

By default, vim-instant-markdown will update the display in realtime.  If that
taxes your system too much, you can specify
>
    let g:instant_markdown_slow = 1
<

before loading the plugin (for example place that in your `~/.vimrc`). This
will cause vim-instant-markdown to only refresh on the following events:

*   No keys have been pressed for a while
*   A while after you leave insert mode
*   You save the file being edited

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_AUTOSTART                       *g:instant_markdown_autostart*
MANUAL START                                       *:InstantMarkdownPreview*
MANUAL STOP                                        *:InstantMarkdownStop*

By default, vim-instant-markdown will automatically launch the preview window
when you open a markdown file. If you want to manually control this behavior,
you can specify
>
    let g:instant_markdown_autostart = 0
<
in your .vimrc. You can always manually trigger preview via the command
`:InstantMarkdownPreview` and stop it via `:InstantMarkdownStop`.

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_OPEN_TO_THE_WORLD       *g:instant_markdown_open_to_the_world*

By default, the server only listens on localhost. To make the server available
to others in your network, edit your .vimrc and add
>
    let g:instant_markdown_open_to_the_world = 1
<

Only use this setting on trusted networks!

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_ALLOW_UNSAFE_CONTENT *g:instant_markdown_allow_unsafe_content*

By default, scripts are blocked. To allow scripts to run, edit your .vimrc and
add
>
    let g:instant_markdown_allow_unsafe_content = 1
<

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_ALLOW_EXTERNAL_CONTENT *g:instant_markdown_allow_external_content*

By default, external resources such as images, stylesheets, frames and plugins
are allowed.  To block such content, edit your .vimrc and add
>
    let g:instant_markdown_allow_external_content = 0
<

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_LOGFILE                           *g:instant_markdown_logfile*

For troubleshooting, server startup and curl communication from Vim to the
server can be logged into a file.
>
    let g:instant_markdown_logfile = '/tmp/instant_markdown.log'
<

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_MATHJAX                           *g:instant_markdown_mathjax*

By default, no TeX code embedded within markdown would be rendered. This option
uses MathJax and launches the node server as .
>
    let g:instant_markdown_mathjax = 1
<
New in version `instant-markdown-d==0.2.0`

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_MERMAID                           *g:instant_markdown_mermaid*

By default, mermaid diagrams are disabled. This option uses
markdown-it-textual-uml and launches the node server as .
>
    let g:instant_markdown_mermaid = 1
<
New in version `instant-markdown-d==0.2.0`

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_BROWSER                        *g:instant_markdown_browser*

By default, browser is detected by `instant-markdown-d` depending on the OS.
 you can set something like
>
    let g:instant_markdown_browser = "firefox --new-window"
<
New in version `instant-markdown-d==0.2.0`

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_PORT                             *g:instant_markdown_port*

Choose a custom port instead of the default `8090`.
>
    let g:instant_markdown_port = 8888
<
New in version `instant-markdown-d==0.2.0`

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_AUTOSCROLL                 *g:instant_markdown_autoscroll*

By default, with version `instant-markdown-d>=0.2.0`, the live preview
auto-scrolls to where your cursor is positioned.  To disable this behaviour,
edit your .vimrc and add
>
    let g:instant_markdown_autoscroll = 0
<
New in version `instant-markdown-d==0.2.0`

------------------------------------------------------------------------------
G:INSTANT_MARKDOWN_THEME                            *g:instant_markdown_theme*

By default, a `light` theme will be activated. A `dark` theme is also
available. And new themes can be contributed into the instant-markdown-d
repository. To enable the `dark` theme by default,
>
    let g:instant_markdown_theme = 'dark'
<
New in version `instant-markdown-d==0.3.0`

--------------------------------------------------------------------------------
4. TIPS AND TRICKS                          *vim-instant-markdown-tips-and-tricks*

- Autostart vim-instant-markdown in certain paths, for example for all
  markdown files under ~/src/someproject

>
    let g:instant_markdown_autostart = 0
    augroup InstantMarkdownGroup
        au! BufRead,BufNewFile,BufEnter ~/src/someproject/*.md let g:instant_markdown_autostart=1
    augroup END
<

vim:tw=82:ft=help