From 84fe692afe220595998d62cc012ff6788ef06093 Mon Sep 17 00:00:00 2001
From: leafOfTree <node_github@163.com>
Date: Wed, 21 Oct 2026 13:52:18 +0000
Subject: [PATCH 1/2] Merge syntax config per block

syntax in g:vim_vue_plugin_config replaced the whole default, so
{'syntax': {'script': ['javascript', 'typescript']}} removed template
and style, which then had no highlight or indent. Replace the default
of each key separately, like vim-svelte-plugin. A block can be removed
by setting it to [].
---
 README.md                   |  1 +
 autoload/vue.vim            |  8 +++++++-
 test/cases/no-css.vim       |  7 +++++--
 test/cases/syntax-merge.vim | 10 ++++++++++
 test/cases/syntax-merge.vue | 13 +++++++++++++
 5 files changed, 36 insertions(+), 3 deletions(-)
 create mode 100644 test/cases/syntax-merge.vim
 create mode 100644 test/cases/syntax-merge.vue

diff --git a/README.md b/README.md
index 8cd49e8..78f481c 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,7 @@ It has the following options
         - `lang="..."` on block tag decides the effective syntax
         - When no valid `lang="..."` is present, the first syntax in the list will be used.
         - By default, only syntax files from `['$VIMRUNTIME', '$VIM/vimfiles', '$HOME/.vim']` are loaded. If none is found, then **full** syntax files, including those from plugins, will be loaded
+    - Each key replaces the default of the same key, so `{'syntax': {'script': ['javascript', 'typescript']}}` keeps `template` as `['html']` and `style` as `['css']`. Set a key to `[]` to remove the block
 - **full_syntax**: *string list*. Syntax whose **full** syntax files will always be loaded
 - **initial_indent**: *string list*. Tag/syntax with initial one tab indent. The format can be `tag.syntax`, `tag`, or `syntax`
 
diff --git a/autoload/vue.vim b/autoload/vue.vim
index 0f08ba6..017cc65 100644
--- a/autoload/vue.vim
+++ b/autoload/vue.vim
@@ -28,10 +28,16 @@ function! s:MergeUserConfigIntoDefault(user)
         \'debug': 0,
         \}
 
+  " Each key of syntax replaces the default of the same key, so blocks not in
+  " user config keep their default syntax
   let user = a:user
   for key in keys(default)
     if has_key(user, key)
-      let default[key] = user[key]
+      if key ==# 'syntax' && type(user[key]) == v:t_dict
+        call extend(default[key], user[key])
+      else
+        let default[key] = user[key]
+      endif
     endif
   endfor
 
diff --git a/test/cases/no-css.vim b/test/cases/no-css.vim
index 394b439..7889f02 100644
--- a/test/cases/no-css.vim
+++ b/test/cases/no-css.vim
@@ -1,5 +1,8 @@
-" Without css syntax, like only script in config
-let g:vim_vue_plugin_config = {'syntax': {'script': ['javascript']}}
+" Without css syntax, like only script in config, removing template and style
+" by []
+let g:vim_vue_plugin_config = {
+      \'syntax': {'script': ['javascript'], 'template': [], 'style': []},
+      \}
 let g:test_flatten = 1
 
 function! Check()
diff --git a/test/cases/syntax-merge.vim b/test/cases/syntax-merge.vim
new file mode 100644
index 0000000..caee50c
--- /dev/null
+++ b/test/cases/syntax-merge.vim
@@ -0,0 +1,10 @@
+" Each key of syntax replaces the default of the same key, so template and
+" style keep html and css
+let g:vim_vue_plugin_config = {'syntax': {'script': ['javascript', 'typescript']}}
+let g:test_flatten = 1
+
+function! Check()
+  call ExpectBlock('<div>', 'template', 'html', 'htmlTemplateBlock')
+  call ExpectBlock('let count', 'script', 'typescript', 'typescriptScriptBlock')
+  call ExpectBlock('color: red', 'style', 'css', 'cssStyleBlock')
+endfunction
diff --git a/test/cases/syntax-merge.vue b/test/cases/syntax-merge.vue
new file mode 100644
index 0000000..ec6928a
--- /dev/null
+++ b/test/cases/syntax-merge.vue
@@ -0,0 +1,13 @@
+<template>
+  <div>{{ count }}</div>
+</template>
+
+<script lang="ts">
+let count: number = 0
+</script>
+
+<style>
+p {
+  color: red;
+}
+</style>

From 7a2f8ac5cdf608a29bb224256ee5a713e024a3c0 Mon Sep 17 00:00:00 2001
From: leafOfTree <node_github@163.com>
Date: Wed, 21 Oct 2026 13:52:54 +0000
Subject: [PATCH 2/2] Add help doc

Add doc/vim-vue-plugin.txt for :help with the configuration and
functions in README.
---
 .gitignore             |   1 +
 README.md              |   2 +
 doc/vim-vue-plugin.txt | 166 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 169 insertions(+)
 create mode 100644 doc/vim-vue-plugin.txt

diff --git a/.gitignore b/.gitignore
index 4d4d57c..7c02170 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ README.html
 test.vue
 .DS_STORE
 test/deps/
+doc/tags
diff --git a/README.md b/README.md
index 78f481c..4a77d49 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,8 @@ Vim syntax and indent plugin for `.vue` files. Mainly inspired by [mxw/vim-jsx][
 
 You could install it just like other plugins. The filetype will be set to `vue`. Feel free to open an issue or a pull request if any questions
 
+See `:help vim-vue-plugin` for the documentation in Vim.
+
 <details>
 <summary><a>How to install</a></summary>
 
diff --git a/doc/vim-vue-plugin.txt b/doc/vim-vue-plugin.txt
new file mode 100644
index 0000000..e85f85a
--- /dev/null
+++ b/doc/vim-vue-plugin.txt
@@ -0,0 +1,166 @@
+*vim-vue-plugin.txt*  Syntax and indent for Vue files
+
+Author: leafOfTree
+License: The Unlicense
+
+==============================================================================
+CONTENTS                                            *vim-vue-plugin-contents*
+
+  1. Introduction ............................... |vim-vue-plugin-intro|
+  2. Configuration .............................. |vim-vue-plugin-config|
+  3. Functions .................................. |vim-vue-plugin-functions|
+  4. Avoid overload ............................. |vim-vue-plugin-overload|
+
+==============================================================================
+1. Introduction                                        *vim-vue-plugin-intro*
+
+Vim syntax and indent plugin for `.vue` files, also `.wpy` files. It loads
+multiple syntax and indent files for `.vue` and enables them to work
+together, with
+
+- Blocks, both <template>/<script>/<style> and custom blocks, with any
+  syntax by lang="...", like pug, typescript, coffee, scss, sass, less and
+  stylus. Syntax plugins need to be installed if not provided by Vim.
+- Attribute, directive and keyword highlight.
+- emmet-vim html/javascript/css filetype detection.
+- Functions to get the current tag or syntax, see
+  |vim-vue-plugin-functions|.
+- A builtin 'foldexpr'.
+
+'filetype' is set to `vue`. Add this plugin to the start of 'runtimepath'
+when installing manually, as Vim 9 and Neovim come with placeholder `vue`
+syntax and indent files: >
+
+  set rtp^=path/to/this_plugin
+<
+==============================================================================
+2. Configuration                                      *vim-vue-plugin-config*
+
+                                                    *g:vim_vue_plugin_config*
+g:vim_vue_plugin_config is the only configuration, set before opening a vue
+file. Its default value: >
+
+  let g:vim_vue_plugin_config = {
+        \'syntax': {
+        \   'template': ['html'],
+        \   'script': ['javascript'],
+        \   'style': ['css'],
+        \},
+        \'full_syntax': [],
+        \'initial_indent': [],
+        \'attribute': 0,
+        \'keyword': 0,
+        \'foldexpr': 0,
+        \'debug': 0,
+        \}
+<
+syntax
+  Block tag name to its syntax list. A string can be used for a list with
+  one item.
+  - lang="..." on the block tag decides the syntax, in double or single
+    quotes or without quotes. `typescript` matches lang="ts" and
+    lang="typescript".
+  - Without lang="...", or if it's not in the list, the first syntax is
+    used.
+  - Syntax files are loaded only from $VIMRUNTIME/syntax, ~/.vim/syntax and
+    $VIM/vimfiles/syntax, or from all of 'runtimepath', including plugins,
+    if not found there.
+  - Each key replaces the default of the same key, so >
+      {'syntax': {'script': ['javascript', 'typescript']}}
+<    keeps `template` as ['html'] and `style` as ['css']. Set a key to [] to
+    remove the block.
+
+full_syntax
+  Syntax list whose files are always loaded from all of 'runtimepath'.
+
+initial_indent
+  Block tag, syntax or tag.syntax like `i18n.json` to indent one level
+  initially. For `.wpy` files, it defaults to ['script', 'style'].
+
+attribute
+  1 to highlight attribute values as expression instead of string.
+
+keyword
+  1 to highlight keywords like `data` and `methods`.
+
+foldexpr
+  1 to use the builtin 'foldexpr' with 'foldmethod' set to `expr`.
+
+debug
+  1 to echo debug messages in |:messages|.
+
+Example, only for demo. Set syntax as little as possible for performance: >
+
+  let g:vim_vue_plugin_config = {
+        \'syntax': {
+        \   'template': ['html', 'pug'],
+        \   'script': ['javascript', 'typescript', 'coffee'],
+        \   'style': ['css', 'scss', 'sass', 'less', 'stylus'],
+        \   'i18n': ['json', 'yaml'],
+        \   'route': 'json',
+        \},
+        \'full_syntax': ['json'],
+        \'initial_indent': ['i18n', 'i18n.json', 'yaml'],
+        \'attribute': 1,
+        \'keyword': 1,
+        \'foldexpr': 1,
+        \}
+<
+Options can be changed later like global variables: >
+
+  let g:vim_vue_plugin_config.foldexpr = 0
+<
+==============================================================================
+3. Functions                                       *vim-vue-plugin-functions*
+
+As there is more than one language in a `.vue` file, different mappings,
+completion and local options may be wanted by tags or syntax, the current
+language.
+
+                                                                *GetVueTag()*
+GetVueTag([{lnum}])
+  Return the block tag at line {lnum}, or the cursor line, like
+  `'template'`, `'script'`, `'style'`, or `''`. Example: >
+
+  autocmd FileType vue inoremap <buffer><expr> : InsertColon()
+
+  function! InsertColon()
+    let tag = GetVueTag()
+    return tag == 'template' ? ':' : ': '
+  endfunction
+<
+                                                             *GetVueSyntax()*
+                                                            *GetVueSubtype()*
+GetVueSyntax()
+  Return the syntax at the cursor line, like `'html'`, `'javascript'`,
+  `'css'`, `'scss'`. GetVueSubtype() is its previous name.
+
+                                                        *OnChangeVueSyntax()*
+                                                       *OnChangeVueSubtype()*
+OnChangeVueSyntax({syntax})
+  If defined in your vimrc, it is called whenever the syntax under the
+  cursor changes. OnChangeVueSubtype() is its previous name. Example: >
+
+  function! OnChangeVueSyntax(syntax)
+    if a:syntax == 'html'
+      setlocal commentstring=<!--%s-->
+    elseif a:syntax =~ 'css'
+      setlocal commentstring=/*%s*/
+    else
+      setlocal commentstring=//%s
+    endif
+  endfunction
+<
+==============================================================================
+4. Avoid overload                                   *vim-vue-plugin-overload*
+
+Most delays come from loading syntax files of many languages.
+`b:current_loading_main_syntax` is set to `vue` while loading, which can be
+used as a condition in syntax files that load others. For example, the
+builtin sass.vim and less.vim load css.vim, which this plugin has loaded: >
+
+  if !exists("b:current_loading_main_syntax")
+    runtime! syntax/css.vim
+  endif
+<
+ vim:tw=78:ts=8:ft=help:norl: