codekingpro/portable-devtools
114k
1*syntax.txt* For Vim version 9.2. Last change: 2026 Apr 142 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7Syntax highlighting *syntax* *syntax-highlighting* *coloring*8 9Syntax highlighting enables Vim to show parts of the text in another font or10color. Those parts can be specific keywords or text matching a pattern. Vim11doesn't parse the whole file (to keep it fast), so the highlighting has its12limitations. Lexical highlighting might be a better name, but since everybody13calls it syntax highlighting we'll stick with that.14 15Vim supports syntax highlighting on all terminals. But since most ordinary16terminals have very limited highlighting possibilities, it works best in the17GUI version, gvim.18 19In the User Manual:20|usr_06.txt| introduces syntax highlighting.21|usr_44.txt| introduces writing a syntax file.22 231. Quick start |:syn-qstart|242. Syntax files |:syn-files|253. Syntax loading procedure |syntax-loading|264. Converting to HTML |2html.vim|275. Syntax file remarks |:syn-file-remarks|286. Defining a syntax |:syn-define|297. :syntax arguments |:syn-arguments|308. Syntax patterns |:syn-pattern|319. Syntax clusters |:syn-cluster|3210. Including syntax files |:syn-include|3311. Synchronizing |:syn-sync|3412. Listing syntax items |:syntax|3513. Colorschemes |color-schemes|3614. Highlight command |:highlight|3715. Linking groups |:highlight-link|3816. Cleaning up |:syn-clear|3917. Highlighting tags |tag-highlight|4018. Window-local syntax |:ownsyntax|4119. Color xterms |xterm-color|4220. When syntax is slow |:syntime|43 44{Vi does not have any of these commands}45 46Syntax highlighting is not available when the |+syntax| feature has been47disabled at compile time.48 49==============================================================================501. Quick start *:syn-qstart*51 52 *:syn-enable* *:syntax-enable*53This command switches on syntax highlighting: >54 55 :syntax enable56 57What this command actually does is to execute the command >58 :source $VIMRUNTIME/syntax/syntax.vim59 60If the VIM environment variable is not set, Vim will try to find61the path in another way (see |$VIMRUNTIME|). Usually this works just62fine. If it doesn't, try setting the VIM environment variable to the63directory where the Vim stuff is located. For example, if your syntax files64are in the "/usr/vim/vim82/syntax" directory, set $VIMRUNTIME to65"/usr/vim/vim82". You must do this in the shell, before starting Vim.66This command also sources the |menu.vim| script when the GUI is running or67will start soon. See |'go-M'| about avoiding that.68 69 *:syn-on* *:syntax-on*70The `:syntax enable` command will keep most of your current color settings.71This allows using `:highlight` commands to set your preferred colors before or72after using this command. If you want Vim to overrule your settings with the73defaults, use: >74 :syntax on75<76 *:hi-normal* *:highlight-normal*77If you are running in the GUI, you can get white text on a black background78with: >79 :highlight Normal guibg=Black guifg=White80For a color terminal see |:hi-normal-cterm|.81For setting up your own colors syntax highlighting see |syncolor|.82 83NOTE: The syntax files on MS-Windows have lines that end in <CR><NL>.84The files for Unix end in <NL>. This means you should use the right type of85file for your system. Although on MS-Windows the right format is86automatically selected if the 'fileformats' option is not empty.87 88NOTE: When using reverse video ("gvim -fg white -bg black"), the default value89of 'background' will not be set until the GUI window is opened, which is after90reading the |gvimrc|. This will cause the wrong default highlighting to be91used. To set the default value of 'background' before switching on92highlighting, include the ":gui" command in the |gvimrc|: >93 94 :gui " open window and set default for 'background'95 :syntax on " start highlighting, use 'background' to set colors96 97NOTE: Using ":gui" in the |gvimrc| means that "gvim -f" won't start in the98foreground! Use ":gui -f" then.99 100 *g:syntax_on*101You can toggle the syntax on/off with this command: >102 :if exists("g:syntax_on") | syntax off | else | syntax enable | endif103 104To put this into a mapping, you can use: >105 :map <F7> :if exists("g:syntax_on") <Bar>106 \ syntax off <Bar>107 \ else <Bar>108 \ syntax enable <Bar>109 \ endif <CR>110[using the |<>| notation, type this literally]111 112Details:113The ":syntax" commands are implemented by sourcing a file. To see exactly how114this works, look in the file:115 command file ~116 :syntax enable $VIMRUNTIME/syntax/syntax.vim117 :syntax on $VIMRUNTIME/syntax/syntax.vim118 :syntax manual $VIMRUNTIME/syntax/manual.vim119 :syntax off $VIMRUNTIME/syntax/nosyntax.vim120Also see |syntax-loading|.121 122NOTE: If displaying long lines is slow and switching off syntax highlighting123makes it fast, consider setting the 'synmaxcol' option to a lower value.124 125==============================================================================1262. Syntax files *:syn-files*127 128The syntax and highlighting commands for one language are normally stored in129a syntax file. The name convention is: "{name}.vim". Where {name} is the130name of the language, or an abbreviation (to fit the name in 8.3 characters,131a requirement in case the file is used on a DOS filesystem).132Examples:133 c.vim perl.vim java.vim html.vim134 cpp.vim sh.vim csh.vim135 136The syntax file can contain any Ex commands, just like a vimrc file. But137the idea is that only commands for a specific language are included. When a138language is a superset of another language, it may include the other one,139for example, the cpp.vim file could include the c.vim file: >140 :so $VIMRUNTIME/syntax/c.vim141 142The .vim files are normally loaded with an autocommand. For example: >143 :au Syntax c runtime! syntax/c.vim144 :au Syntax cpp runtime! syntax/cpp.vim145These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.146 147 148MAKING YOUR OWN SYNTAX FILES *mysyntaxfile*149 150When you create your own syntax files, and you want to have Vim use these151automatically with ":syntax enable", do this:152 1531. Create your user runtime directory. You would normally use the first item154 of the 'runtimepath' option. Example for Unix: >155 mkdir ~/.vim156 1572. Create a directory in there called "syntax". For Unix: >158 mkdir ~/.vim/syntax159 1603. Write the Vim syntax file. Or download one from the internet. Then write161 it in your syntax directory. For example, for the "mine" syntax: >162 :w ~/.vim/syntax/mine.vim163 164Now you can start using your syntax file manually: >165 :set syntax=mine166You don't have to exit Vim to use this.167 168If you also want Vim to detect the type of file, see |new-filetype|.169 170If you are setting up a system with many users and you don't want each user171to add the same syntax file, you can use another directory from 'runtimepath'.172 173 174ADDING TO AN EXISTING SYNTAX FILE *mysyntaxfile-add*175 176If you are mostly satisfied with an existing syntax file, but would like to177add a few items or change the highlighting, follow these steps:178 1791. Create your user directory from 'runtimepath', see above.180 1812. Create a directory in there called "after/syntax". For Unix: >182 mkdir -p ~/.vim/after/syntax183 1843. Write a Vim script that contains the commands you want to use. For185 example, to change the colors for the C syntax: >186 highlight cComment ctermfg=Green guifg=Green187 1884. Write that file in the "after/syntax" directory. Use the name of the189 syntax, with ".vim" added. For our C syntax: >190 :w ~/.vim/after/syntax/c.vim191 192That's it. The next time you edit a C file the Comment color will be193different. You don't even have to restart Vim.194 195If you have multiple files, you can use the filetype as the directory name.196All the "*.vim" files in this directory will be used, for example:197 ~/.vim/after/syntax/c/one.vim198 ~/.vim/after/syntax/c/two.vim199 200 201REPLACING AN EXISTING SYNTAX FILE *mysyntaxfile-replace*202 203If you don't like a distributed syntax file, or you have downloaded a new204version, follow the same steps as for |mysyntaxfile| above. Just make sure205that you write the syntax file in a directory that is early in 'runtimepath'.206Vim will only load the first syntax file found, assuming that it sets207b:current_syntax.208 209 210NAMING CONVENTIONS *group-name* *{group-name}* *E669* *W18*211 212A syntax group name is to be used for syntax items that match the same kind of213thing. These are then linked to a highlight group that specifies the color.214A syntax group name doesn't specify any color or attributes itself.215 216The name for a highlight or syntax group must consist of ASCII letters,217digits, underscores, dots, or hyphens. As a regexp: "[a-zA-Z0-9_.-]*".218However, Vim does not give an error when using other characters. The maximum219length of a group name is about 200 bytes. *E1249*220 221To be able to allow each user to pick their favorite set of colors, there must222be preferred names for highlight groups that are common for many languages.223These are the suggested group names (if syntax highlighting works properly224you can see the actual color, except for "Ignore"):225 226 *Comment any comment227 228 *Constant any constant229 String a string constant: "this is a string"230 Character a character constant: 'c', '\n'231 Number a number constant: 234, 0xff232 Boolean a boolean constant: TRUE, false233 Float a floating point constant: 2.3e10234 235 *Identifier any variable name236 Function function name (also: methods for classes)237 238 *Statement any statement239 Conditional if, then, else, endif, switch, etc.240 Repeat for, do, while, etc.241 Label case, default, etc.242 Operator "sizeof", "+", "*", etc.243 Keyword any other keyword244 Exception try, catch, throw245 246 *PreProc generic Preprocessor247 Include preprocessor #include248 Define preprocessor #define249 Macro same as Define250 PreCondit preprocessor #if, #else, #endif, etc.251 252 *Type int, long, char, etc.253 StorageClass static, register, volatile, etc.254 Structure struct, union, enum, etc.255 Typedef A typedef256 257 *Special any special symbol258 SpecialChar special character in a constant259 Tag you can use CTRL-] on this260 Delimiter character that needs attention261 SpecialComment special things inside a comment262 Debug debugging statements263 264 *Underlined text that stands out, HTML links265 *Bold bold text266 *Italic italic text267 *BoldItalic bold and italic text268 269 *Ignore left blank, hidden |hl-Ignore|270 271 *Error any erroneous construct272 273 *Todo anything that needs extra attention; mostly the274 keywords TODO FIXME and XXX275 276 *Added added line in a diff277 *Changed changed line in a diff278 *Removed removed line in a diff279 280The names marked with * are the preferred groups; the others are minor groups.281For the preferred groups, the "syntax.vim" file contains default highlighting.282The minor groups are linked to the preferred groups, so they get the same283highlighting. You can override these defaults by using ":highlight" commands284after sourcing the "syntax.vim" file.285 286Note that highlight group names are not case sensitive. "String" and "string"287can be used for the same group.288 289The following names are reserved and cannot be used as a group name:290 NONE ALL ALLBUT contains contained291 292 *hl-Ignore*293When using the Ignore group, you may also consider using the conceal294mechanism. See |conceal|.295 296==============================================================================2973. Syntax loading procedure *syntax-loading*298 299This explains the details that happen when the command ":syntax enable" is300issued. When Vim initializes itself, it finds out where the runtime files are301located. This is used here as the variable |$VIMRUNTIME|.302 303":syntax enable" and ":syntax on" do the following:304 305 Source $VIMRUNTIME/syntax/syntax.vim306 |307 +- Clear out any old syntax by sourcing $VIMRUNTIME/syntax/nosyntax.vim308 |309 +- Source first syntax/synload.vim in 'runtimepath'310 | |311 | +- Setup the colors for syntax highlighting. If a color scheme is312 | | defined it is loaded again with ":colors {name}". Otherwise313 | | ":runtime! syntax/syncolor.vim" is used. ":syntax on" overrules314 | | existing colors, ":syntax enable" only sets groups that weren't315 | | set yet.316 | |317 | +- Set up syntax autocmds to load the appropriate syntax file when318 | | the 'syntax' option is set. *synload-1*319 | |320 | +- Source the user's optional file, from the |mysyntaxfile| variable.321 | This is for backwards compatibility with Vim 5.x only. *synload-2*322 |323 +- Do ":filetype on", which does ":runtime! filetype.vim". It loads any324 | filetype.vim files found. It should always Source325 | $VIMRUNTIME/filetype.vim, which does the following.326 | |327 | +- Install autocmds based on suffix to set the 'filetype' option328 | | This is where the connection between file name and file type is329 | | made for known file types. *synload-3*330 | |331 | +- Source the user's optional file, from the *myfiletypefile*332 | | variable. This is for backwards compatibility with Vim 5.x only.333 | | *synload-4*334 | |335 | +- Install one autocommand which sources scripts.vim when no file336 | | type was detected yet. *synload-5*337 | |338 | +- Source $VIMRUNTIME/menu.vim, to setup the Syntax menu. |menu.vim|339 |340 +- Install a FileType autocommand to set the 'syntax' option when a file341 | type has been detected. *synload-6*342 |343 +- Execute syntax autocommands to start syntax highlighting for each344 already loaded buffer.345 346 347Upon loading a file, Vim finds the relevant syntax file as follows:348 349 Loading the file triggers the BufReadPost autocommands.350 |351 +- If there is a match with one of the autocommands from |synload-3|352 | (known file types) or |synload-4| (user's file types), the 'filetype'353 | option is set to the file type.354 |355 +- The autocommand at |synload-5| is triggered. If the file type was not356 | found yet, then scripts.vim is searched for in 'runtimepath'. This357 | should always load $VIMRUNTIME/scripts.vim, which does the following.358 | |359 | +- Source the user's optional file, from the *myscriptsfile*360 | | variable. This is for backwards compatibility with Vim 5.x only.361 | |362 | +- If the file type is still unknown, check the contents of the file,363 | again with checks like "getline(1) =~ pattern" as to whether the364 | file type can be recognized, and set 'filetype'.365 |366 +- When the file type was determined and 'filetype' was set, this367 | triggers the FileType autocommand |synload-6| above. It sets368 | 'syntax' to the determined file type.369 |370 +- When the 'syntax' option was set above, this triggers an autocommand371 | from |synload-1| (and |synload-2|). This find the main syntax file in372 | 'runtimepath', with this command:373 | runtime! syntax/<name>.vim374 |375 +- Any other user installed FileType or Syntax autocommands are376 triggered. This can be used to change the highlighting for a specific377 syntax.378 379==============================================================================3804. Conversion to HTML *2html.vim* *convert-to-HTML*381 3822html is not a syntax file itself, but a script that converts the current383window into HTML. Vim opens a new window in which it builds the HTML file.384 385After you save the resulting file, you can view it with any browser. The386colors should be exactly the same as you see them in Vim. With387|g:html_line_ids| you can jump to specific lines by adding (for example) #L123388or #123 to the end of the URL in your browser's address bar. And with389|g:html_dynamic_folds| enabled, you can show or hide the text that is folded390in Vim.391 392You are not supposed to set the 'filetype' or 'syntax' option to "2html"!393Source the script to convert the current file: >394 395 :runtime! syntax/2html.vim396<397Many variables affect the output of 2html.vim; see below. Any of the on/off398options listed below can be enabled or disabled by setting them explicitly to399the desired value, or restored to their default by removing the variable using400|:unlet|.401 402Remarks:403- Some truly ancient browsers may not show the background colors.404- From most browsers you can also print the file (in color)!405- The latest TOhtml may actually work with older versions of Vim, but some406 features such as conceal support will not function, and the colors may be407 incorrect for an old Vim without GUI support compiled in.408 409Here is an example how to run the script over all .c and .h files from a410Unix shell: >411 for f in *.[ch]; do gvim -f +"syn on" +"run! syntax/2html.vim" +"wq" +"q" $f; done412<413 *g:html_start_line* *g:html_end_line*414To restrict the conversion to a range of lines, use a range with the |:TOhtml|415command below, or set "g:html_start_line" and "g:html_end_line" to the first416and last line to be converted. Example, using the last set Visual area: >417 418 :let g:html_start_line = line("'<")419 :let g:html_end_line = line("'>")420 :runtime! syntax/2html.vim421<422 *:TOhtml*423:[range]TOhtml The ":TOhtml" command is defined in a standard plugin.424 This command will source |2html.vim| for you. When a425 range is given, this command sets |g:html_start_line|426 and |g:html_end_line| to the start and end of the427 range, respectively. Default range is the entire428 buffer.429 430 If the current window is part of a |diff|, unless431 |g:html_diff_one_file| is set, :TOhtml will convert432 all windows which are part of the diff in the current433 tab and place them side-by-side in a <table> element434 in the generated HTML. With |g:html_line_ids| you can435 jump to lines in specific windows with (for example)436 #W1L42 for line 42 in the first diffed window, or437 #W3L87 for line 87 in the third.438 439 Examples: >440 441 :10,40TOhtml " convert lines 10-40 to html442 :'<,'>TOhtml " convert current/last visual selection443 :TOhtml " convert entire buffer444<445 *g:html_diff_one_file*446Default: 0.447When 0, and using |:TOhtml| all windows involved in a |diff| in the current tab448page are converted to HTML and placed side-by-side in a <table> element. When4491, only the current buffer is converted.450Example: >451 452 let g:html_diff_one_file = 1453<454 *g:html_whole_filler*455Default: 0.456When 0, if |g:html_diff_one_file| is 1, a sequence of more than 3 filler lines457is displayed as three lines with the middle line mentioning the total number458of inserted lines.459When 1, always display all inserted lines as if |g:html_diff_one_file| were460not set.461>462 :let g:html_whole_filler = 1463<464 *TOhtml-performance* *g:html_no_progress*465Default: 0.466When 0, display a progress bar in the statusline for each major step in the4672html.vim conversion process.468When 1, do not display the progress bar. This offers a minor speed469improvement but you won't have any idea how much longer the conversion might470take; for big files it can take a long time!471Example: >472 473 let g:html_no_progress = 1474<475You can obtain better performance improvements by also instructing Vim to not476run interactively, so that too much time is not taken to redraw as the script477moves through the buffer, switches windows, and the like: >478 479 vim -E -s -c "let g:html_no_progress=1" -c "syntax on" -c "set ft=c" -c "runtime syntax/2html.vim" -cwqa myfile.c480<481Note that the -s flag prevents loading your .vimrc and any plugins, so you482need to explicitly source/enable anything that will affect the HTML483conversion. See |-E| and |-s-ex| for details. It is probably best to create a484script to replace all the -c commands and use it with the -u flag instead of485specifying each command separately.486 487 *hl-TOhtmlProgress* *TOhtml-progress-color*488When displayed, the progress bar will show colored boxes along the statusline489as the HTML conversion proceeds. By default, the background color as the490current "DiffDelete" highlight group is used. If "DiffDelete" and491"StatusLine" have the same background color, TOhtml will automatically adjust492the color to differ. If you do not like the automatically selected colors,493you can define your own highlight colors for the progress bar. Example: >494 495 hi TOhtmlProgress guifg=#c0ffee ctermbg=7496<497 *g:html_number_lines*498Default: Current 'number' setting.499When 0, buffer text is displayed in the generated HTML without line numbering.500When 1, a column of line numbers is added to the generated HTML with the same501highlighting as the line number column in Vim (|hl-LineNr|).502Force line numbers even if 'number' is not set: >503 :let g:html_number_lines = 1504Force to omit the line numbers: >505 :let g:html_number_lines = 0506Go back to the default to use 'number' by deleting the variable: >507 :unlet g:html_number_lines508<509 *g:html_line_ids*510Default: 1 if |g:html_number_lines| is set, 0 otherwise.511When 1, adds an HTML id attribute to each line number, or to an empty <span>512inserted for that purpose if no line numbers are shown. This ID attribute513takes the form of L123 for single-buffer HTML pages, or W2L123 for diff-view514pages, and is used to jump to a specific line (in a specific window of a diff515view). Javascript is inserted to open any closed dynamic folds516(|g:html_dynamic_folds|) containing the specified line before jumping. The517javascript also allows omitting the window ID in the url, and the leading L.518For example: >519 520 page.html#L123 jumps to line 123 in a single-buffer file521 page.html#123 does the same522 523 diff.html#W1L42 jumps to line 42 in the first window in a diff524 diff.html#42 does the same525<526 *g:html_use_css*527Default: 1.528When 1, generate valid HTML 5 markup with CSS styling, supported in all modern529browsers and many old browsers.530When 0, generate <font> tags and similar outdated markup. This is not531recommended but it may work better in really old browsers, email clients,532forum posts, and similar situations where basic CSS support is unavailable.533Example: >534 :let g:html_use_css = 0535<536 *g:html_ignore_conceal*537Default: 0.538When 0, concealed text is removed from the HTML and replaced with a character539from |:syn-cchar| or 'listchars' as appropriate, depending on the current540value of 'conceallevel'.541When 1, include all text from the buffer in the generated HTML, even if it is542|conceal|ed.543 544Either of the following commands will ensure that all text in the buffer is545included in the generated HTML (unless it is folded): >546 :let g:html_ignore_conceal = 1547 :setl conceallevel=0548<549 *g:html_ignore_folding*550Default: 0.551When 0, text in a closed fold is replaced by the text shown for the fold in552Vim (|fold-foldtext|). See |g:html_dynamic_folds| if you also want to allow553the user to expand the fold as in Vim to see the text inside.554When 1, include all text from the buffer in the generated HTML; whether the555text is in a fold has no impact at all. |g:html_dynamic_folds| has no effect.556 557Either of these commands will ensure that all text in the buffer is included558in the generated HTML (unless it is concealed): >559 zR560 :let g:html_ignore_folding = 1561<562 *g:html_dynamic_folds*563Default: 0.564When 0, text in a closed fold is not included at all in the generated HTML.565When 1, generate javascript to open a fold and show the text within, just like566in Vim.567 568Setting this variable to 1 causes 2html.vim to always use CSS for styling,569regardless of what |g:html_use_css| is set to.570 571This variable is ignored when |g:html_ignore_folding| is set.572>573 :let g:html_dynamic_folds = 1574<575 *g:html_no_foldcolumn*576Default: 0.577When 0, if |g:html_dynamic_folds| is 1, generate a column of text similar to578Vim's foldcolumn (|fold-foldcolumn|) the user can click on to toggle folds579open or closed. The minimum width of the generated text column is the current580'foldcolumn' setting.581When 1, do not generate this column; instead, hovering the mouse cursor over582folded text will open the fold as if |g:html_hover_unfold| were set.583>584 :let g:html_no_foldcolumn = 1585<586 *TOhtml-uncopyable-text* *g:html_prevent_copy*587Default: Empty string.588This option prevents certain regions of the generated HTML from being copied,589when you select all text in document rendered in a browser and copy it.590Useful for allowing users to copy-paste only the source text even if a fold591column or line numbers are shown in the generated content. Specify regions to592be affected in this way as follows:593 f: fold column594 n: line numbers (also within fold text)595 t: fold text596 d: diff filler597 598Example, to make the fold column and line numbers uncopyable: >599 :let g:html_prevent_copy = "fn"600<601The method used to prevent copying in the generated page depends on the value602of |g:html_use_input_for_pc|.603 604 *g:html_use_input_for_pc*605Default: "none"606If |g:html_prevent_copy| is non-empty, then:607 608When "all", read-only <input> elements are used in place of normal text for609uncopyable regions. In some browsers, especially older browsers, after610selecting an entire page and copying the selection, the <input> tags are not611pasted with the page text. If |g:html_no_invalid| is 0, the <input> tags have612invalid type; this works in more browsers, but the page will not validate.613Note: This method does NOT work in recent versions of Chrome and equivalent614browsers; the <input> tags get pasted with the text.615 616When "fallback" (default value), the same <input> elements are generated for617older browsers, but newer browsers (detected by CSS feature query) hide the618<input> elements and instead use generated content in an ::before619pseudoelement to display the uncopyable text. This method should work with620the largest number of browsers, both old and new.621 622When "none", the <input> elements are not generated at all. Only the623generated-content method is used. This means that old browsers, notably624Internet Explorer, will either copy the text intended not to be copyable, or625the non-copyable text may not appear at all. However, this is the most626standards-based method, and there will be much less markup.627 628 *g:html_no_invalid*629Default: 0.630When 0, if |g:html_prevent_copy| is non-empty and |g:html_use_input_for_pc| is631not "none", an invalid attribute is intentionally inserted into the <input>632element for the uncopyable areas. This prevents pasting the <input> elements633in some applications. Specifically, some versions of Microsoft Word will not634paste the <input> elements if they contain this invalid attribute. When 1, no635invalid markup is inserted, and the generated page should validate. However,636<input> elements may be pasted into some applications and can be difficult to637remove afterward.638 639 *g:html_hover_unfold*640Default: 0.641When 0, the only way to open a fold generated by 2html.vim with642|g:html_dynamic_folds| set, is to click on the generated fold column.643When 1, use CSS 2.0 to allow the user to open a fold by moving the mouse644cursor over the displayed fold text. This is useful to allow users with645disabled javascript to view the folded text.646 647Note that old browsers (notably Internet Explorer 6) will not support this648feature. Browser-specific markup for IE6 is included to fall back to the649normal CSS1 styling so that the folds show up correctly for this browser, but650they will not be openable without a foldcolumn.651>652 :let g:html_hover_unfold = 1653<654 *g:html_id_expr*655Default: ""656Dynamic folding and jumping to line IDs rely on unique IDs within the document657to work. If generated HTML is copied into a larger document, these IDs are no658longer guaranteed to be unique. Set g:html_id_expr to an expression Vim can659evaluate to get a unique string to append to each ID used in a given document,660so that the full IDs will be unique even when combined with other content in a661larger HTML document. Example, to append _ and the buffer number to each ID: >662 663 :let g:html_id_expr = '"_" .. bufnr("%")'664<665To append a string "_mystring" to the end of each ID: >666 667 :let g:html_id_expr = '"_mystring"'668<669Note: When converting a diff view to HTML, the expression will only be670evaluated for the first window in the diff, and the result used for all the671windows.672 673 *TOhtml-wrap-text* *g:html_pre_wrap*674Default: Current 'wrap' setting.675When 0, if |g:html_no_pre| is 0 or unset, the text in the generated HTML does676not wrap at the edge of the browser window.677When 1, if |g:html_use_css| is 1, the CSS 2.0 "white-space:pre-wrap" value is678used, causing the text to wrap at whitespace at the edge of the browser679window.680Explicitly enable text wrapping: >681 :let g:html_pre_wrap = 1682Explicitly disable wrapping: >683 :let g:html_pre_wrap = 0684Go back to default, determine wrapping from 'wrap' setting: >685 :unlet g:html_pre_wrap686<687 *g:html_no_pre*688Default: 0.689When 0, buffer text in the generated HTML is surrounded by <pre>...</pre>690tags. Series of whitespace is shown as in Vim without special markup, and tab691characters can be included literally (see |g:html_expand_tabs|).692When 1 (not recommended), the <pre> tags are omitted, and a plain <div> is693used instead. Whitespace is replaced by a series of character694references, and <br> is used to end each line. This is another way to allow695text in the generated HTML is wrap (see |g:html_pre_wrap|) which also works in696old browsers, but may cause noticeable differences between Vim's display and697the rendered page generated by 2html.vim.698>699 :let g:html_no_pre = 1700<701 *g:html_no_doc*702Default: 0.703When 1 it doesn't generate a full HTML document with a DOCTYPE, <head>,704<body>, etc. If |g:html_use_css| is enabled (the default) you'll have to705define the CSS manually. The |g:html_dynamic_folds| and |g:html_line_ids|706settings (off by default) also insert some JavaScript.707 708 709 *g:html_no_links*710Default: 0.711Don't generate <a> tags for text that looks like an URL.712 713 *g:html_no_modeline*714Default: 0.715Don't generate a modeline disabling folding.716 717 *g:html_expand_tabs*718Default: 0 if 'tabstop' is 8, 'expandtab' is 0, 'vartabstop' is not in use,719 and no fold column or line numbers occur in the generated HTML;720 1 otherwise.721When 1, <Tab> characters in the buffer text are replaced with an appropriate722number of space characters, or references if |g:html_no_pre| is 1.723When 0, if |g:html_no_pre| is 0 or unset, <Tab> characters in the buffer text724are included as-is in the generated HTML. This is useful for when you want to725allow copy and paste from a browser without losing the actual whitespace in726the source document. Note that this can easily break text alignment and727indentation in the HTML, unless set by default.728 729Force |2html.vim| to keep <Tab> characters: >730 :let g:html_expand_tabs = 0731<732Force tabs to be expanded: >733 :let g:html_expand_tabs = 1734<735 *TOhtml-encoding-detect* *TOhtml-encoding*736It is highly recommended to set your desired encoding with737|g:html_use_encoding| for any content which will be placed on a web server.738 739If you do not specify an encoding, |2html.vim| uses the preferred IANA name740for the current value of 'fileencoding' if set, or 'encoding' if not.741'encoding' is always used for certain 'buftype' values. 'fileencoding' will742be set to match the chosen document encoding.743 744Automatic detection works for the encodings mentioned specifically by name in745|encoding-names|, but TOhtml will only automatically use those encodings with746wide browser support. However, you can override this to support specific747encodings that may not be automatically detected by default (see options748below). See http://www.iana.org/assignments/character-sets for the IANA749names.750 751Note: By default all Unicode encodings are converted to UTF-8 with no BOM in752the generated HTML, as recommended by W3C:753 754 http://www.w3.org/International/questions/qa-choosing-encodings755 http://www.w3.org/International/questions/qa-byte-order-mark756 757 *g:html_use_encoding*758Default: none, uses IANA name for current 'fileencoding' as above.759To overrule all automatic charset detection, set g:html_use_encoding to the760name of the charset to be used. It is recommended to set this variable to761something widely supported, like UTF-8, for anything you will be hosting on a762webserver: >763 :let g:html_use_encoding = "UTF-8"764You can also use this option to omit the line that specifies the charset765entirely, by setting g:html_use_encoding to an empty string (NOT recommended): >766 :let g:html_use_encoding = ""767To go back to the automatic mechanism, delete the |g:html_use_encoding|768variable: >769 :unlet g:html_use_encoding770<771 *g:html_encoding_override*772Default: none, autoload/tohtml.vim contains default conversions for encodings773 mentioned by name at |encoding-names|.774This option allows |2html.vim| to detect the correct 'fileencoding' when you775specify an encoding with |g:html_use_encoding| which is not in the default776list of conversions.777 778This is a dictionary of charset-encoding pairs that will replace existing779pairs automatically detected by TOhtml, or supplement with new pairs.780 781Detect the HTML charset "windows-1252" as the encoding "8bit-cp1252": >782 :let g:html_encoding_override = {'windows-1252': '8bit-cp1252'}783<784 *g:html_charset_override*785Default: none, autoload/tohtml.vim contains default conversions for encodings786 mentioned by name at |encoding-names| and which have wide787 browser support.788This option allows |2html.vim| to detect the HTML charset for any789'fileencoding' or 'encoding' which is not detected automatically. You can790also use it to override specific existing encoding-charset pairs. For791example, TOhtml will by default use UTF-8 for all Unicode/UCS encodings. To792use UTF-16 and UTF-32 instead, use: >793 :let g:html_charset_override = {'ucs-4': 'UTF-32', 'utf-16': 'UTF-16'}794 795Note that documents encoded in either UTF-32 or UTF-16 have known796compatibility problems with some major browsers.797 798 *g:html_font*799Default: "monospace"800You can specify the font or fonts used in the converted document using801g:html_font. If this option is set to a string, then the value will be802surrounded with single quotes. If this option is set to a list then each list803item is surrounded by single quotes and the list is joined with commas.804Either way, "monospace" is added as the fallback generic family name and the805entire result used as the font family (using CSS) or font face (if not using806CSS). Examples: >807 808 " font-family: 'Consolas', monospace;809 :let g:html_font = "Consolas"810 811 " font-family: 'DejaVu Sans Mono', 'Consolas', monospace;812 :let g:html_font = ["DejaVu Sans Mono", "Consolas"]813<814 *convert-to-XML* *convert-to-XHTML* *g:html_use_xhtml*815Default: 0.816When 0, generate standard HTML 4.01 (strict when possible).817When 1, generate XHTML 1.0 instead (XML compliant HTML).818>819 :let g:html_use_xhtml = 1820<821==============================================================================8225. Syntax file remarks *:syn-file-remarks*823 824 *b:current_syntax-variable*825Vim stores the name of the syntax that has been loaded in the826"b:current_syntax" variable. You can use this if you want to load other827settings, depending on which syntax is active. Example: >828 :au BufReadPost * if b:current_syntax == "csh"829 :au BufReadPost * do-some-things830 :au BufReadPost * endif831 832 833 834ABEL *abel.vim* *ft-abel-syntax*835 836ABEL highlighting provides some user-defined options. To enable them, assign837any value to the respective variable. Example: >838 :let abel_obsolete_ok=1839To disable them use ":unlet". Example: >840 :unlet abel_obsolete_ok841 842Variable Highlight ~843abel_obsolete_ok obsolete keywords are statements, not errors844abel_cpp_comments_illegal do not interpret '//' as inline comment leader845 846 847ADA848 849See |ft-ada-syntax|850 851 852ANT *ant.vim* *ft-ant-syntax*853 854The ant syntax file provides syntax highlighting for javascript and python855by default. Syntax highlighting for other script languages can be installed856by the function AntSyntaxScript(), which takes the tag name as first argument857and the script syntax file name as second argument. Example: >858 859 :call AntSyntaxScript('perl', 'perl.vim')860 861will install syntax perl highlighting for the following ant code >862 863 <script language = 'perl'><![CDATA[864 # everything inside is highlighted as perl865 ]]></script>866 867See |mysyntaxfile-add| for installing script languages permanently.868 869 870APACHE *apache.vim* *ft-apache-syntax*871 872The apache syntax file provides syntax highlighting for Apache HTTP server873version 2.2.3.874 875 876 *asm.vim* *asmh8300.vim* *nasm.vim* *masm.vim* *asm68k*877ASSEMBLY *ft-asm-syntax* *ft-asmh8300-syntax* *ft-nasm-syntax*878 *ft-masm-syntax* *ft-asm68k-syntax* *fasm.vim*879 880Files matching "*.i" could be Progress or Assembly. If the automatic881detection doesn't work for you, or you don't edit Progress at all, use this in882your startup vimrc: >883 :let filetype_i = "asm"884Replace "asm" with the type of assembly you use.885 886There are many types of assembly languages that all use the same file name887extensions. Therefore you will have to select the type yourself, or add a888line in the assembly file that Vim will recognize. Currently these syntax889files are included:890 asm GNU assembly (usually have .s or .S extension and were891 already built using C compiler such as GCC or CLANG)892 asm68k Motorola 680x0 assembly893 asmh8300 Hitachi H-8300 version of GNU assembly894 ia64 Intel Itanium 64895 fasm Flat assembly (http://flatassembler.net)896 masm Microsoft assembly (.masm files are compiled with897 Microsoft's Macro Assembler. This is only supported898 for x86, x86_64, ARM and AARCH64 CPU families)899 nasm Netwide assembly900 tasm Turbo Assembly (with opcodes 80x86 up to Pentium, and901 MMX)902 pic PIC assembly (currently for PIC16F84)903 904The most flexible is to add a line in your assembly file containing: >905 asmsyntax=nasm906Replace "nasm" with the name of the real assembly syntax. This line must be907one of the first five lines in the file. No non-white text must be908immediately before or after this text. Note that specifying asmsyntax=foo is909equivalent to setting ft=foo in a |modeline|, and that in case of a conflict910between the two settings the one from the modeline will take precedence (in911particular, if you have ft=asm in the modeline, you will get the GNU syntax912highlighting regardless of what is specified as asmsyntax).913 914The syntax type can always be overruled for a specific buffer by setting the915b:asmsyntax variable: >916 :let b:asmsyntax = "nasm"917 918If b:asmsyntax is not set, either automatically or by hand, then the value of919the global variable asmsyntax is used. This can be seen as a default assembly920language: >921 :let asmsyntax = "nasm"922 923As a last resort, if nothing is defined, the "asm" syntax is used.924 925 926Netwide assembler (nasm.vim) optional highlighting ~927 928To enable a feature: >929 :let {variable}=1|set syntax=nasm930To disable a feature: >931 :unlet {variable} |set syntax=nasm932 933Variable Highlight ~934nasm_loose_syntax unofficial parser allowed syntax not as Error935 (parser dependent; not recommended)936nasm_ctx_outside_macro contexts outside macro not as Error937nasm_no_warn potentially risky syntax not as ToDo938 939ASTRO *astro.vim* *ft-astro-syntax*940 941Configuration942 943The following variables control certain syntax highlighting features.944You can add them to your .vimrc.945 946To enable TypeScript and TSX for ".astro" files (default "disable"): >947 let g:astro_typescript = "enable"948<949To enable Stylus for ".astro" files (default "disable"): >950 let g:astro_stylus = "enable"951<952NOTE: You need to install an external plugin to support stylus in astro files.953 954 955ASPPERL *ft-aspperl-syntax*956ASPVBS *ft-aspvbs-syntax*957 958*.asp and *.asa files could be either Perl or Visual Basic script. Since it's959hard to detect this you can set two global variables to tell Vim what you are960using. For Perl script use: >961 :let g:filetype_asa = "aspperl"962 :let g:filetype_asp = "aspperl"963For Visual Basic use: >964 :let g:filetype_asa = "aspvbs"965 :let g:filetype_asp = "aspvbs"966 967ASYMPTOTE *asy.vim* *ft-asy-syntax*968 969By default, only basic Asymptote keywords are highlighted. To highlight970extended geometry keywords: >971 972 :let g:asy_syn_plain = 1973 974and for highlighting keywords related to 3D constructions: >975 976 :let g:asy_syn_three = 1977 978By default, Asymptote-defined colors (e.g: lightblue) are highlighted. To979highlight TeX-defined colors (e.g: BlueViolet) use: >980 981 :let g:asy_syn_texcolors = 1982 983or for Xorg colors (e.g: AliceBlue): >984 985 :let g:asy_syn_x11colors = 1986 987BAAN *baan.vim* *baan-syntax*988 989The baan.vim gives syntax support for BaanC of release BaanIV up to SSA ERP LN990for both 3 GL and 4 GL programming. Large number of standard991defines/constants are supported.992 993Some special violation of coding standards will be signalled when one specify994in ones |.vimrc|: >995 let baan_code_stds=1996 997*baan-folding*998 999Syntax folding can be enabled at various levels through the variables1000mentioned below (Set those in your |.vimrc|). The more complex folding on1001source blocks and SQL can be CPU intensive.1002 1003To allow any folding and enable folding at function level use: >1004 let baan_fold=11005Folding can be enabled at source block level as if, while, for ,... The1006indentation preceding the begin/end keywords has to match (spaces are not1007considered equal to a tab). >1008 let baan_fold_block=11009Folding can be enabled for embedded SQL blocks as SELECT, SELECTDO,1010SELECTEMPTY, ... The indentation preceding the begin/end keywords has to1011match (spaces are not considered equal to a tab). >1012 let baan_fold_sql=11013Note: Block folding can result in many small folds. It is suggested to |:set|1014the options 'foldminlines' and 'foldnestmax' in |.vimrc| or use |:setlocal| in1015.../after/syntax/baan.vim (see |after-directory|). Eg: >1016 set foldminlines=51017 set foldnestmax=61018 1019 1020BASIC *basic.vim* *vb.vim* *ft-basic-syntax* *ft-vb-syntax*1021 1022Both Visual Basic and "normal" BASIC use the extension ".bas". To detect1023which one should be used, Vim checks for the string "VB_Name" in the first1024five lines of the file. If it is not found, filetype will be "basic",1025otherwise "vb". Files with the ".frm" extension will always be seen as Visual1026Basic.1027 1028If the automatic detection doesn't work for you or you only edit, for1029example, FreeBASIC files, use this in your startup vimrc: >1030 :let filetype_bas = "freebasic"1031 1032 1033C *c.vim* *ft-c-syntax*1034 1035A few things in C highlighting are optional. To enable them assign any value1036(including zero) to the respective variable. Example: >1037 :let c_comment_strings = 11038 :let c_no_bracket_error = 01039To disable them use `:unlet`. Example: >1040 :unlet c_comment_strings1041Setting the value to zero doesn't work!1042 1043An alternative is to switch to the C++ highlighting: >1044 :set filetype=cpp1045 1046Variable Highlight ~1047*c_gnu* GNU gcc specific items1048*c_comment_strings* strings and numbers inside a comment1049*c_space_errors* trailing white space and spaces before a <Tab>1050*c_no_trail_space_error* ... but no trailing spaces1051*c_no_tab_space_error* ... but no spaces before a <Tab>1052*c_no_bracket_error* don't highlight {}; inside [] as errors1053*c_no_curly_error* don't highlight {}; inside [] and () as errors;1054 ...except { and } in first column1055 Default is to highlight them, otherwise you1056 can't spot a missing ")".1057*c_curly_error* highlight a missing } by finding all pairs; this1058 forces syncing from the start of the file, can be slow1059*c_no_ansi* don't do standard ANSI types and constants1060*c_ansi_typedefs* ... but do standard ANSI types1061*c_ansi_constants* ... but do standard ANSI constants1062*c_no_utf* don't highlight \u and \U in strings1063*c_syntax_for_h* use C syntax for *.h files instead of C++/ObjC/ObjC++1064 (NOTE: This variable is deprecated and no longer1065 necessary, as *.h files now default to C, unless the1066 file contains C++ or Objective-C syntax. If the1067 automated detection fails, the default filetype can1068 be adjusted using `g:filetype_h`.)1069*c_no_if0* don't highlight "#if 0" blocks as comments1070*c_no_cformat* don't highlight %-formats in strings1071*c_no_c99* don't highlight C99 standard items1072*c_no_c11* don't highlight C11 standard items1073*c_no_c23* don't highlight C23 standard items1074*c_no_bsd* don't highlight BSD specific types1075*c_functions* highlight function calls and definitions1076*c_function_pointers* highlight function pointers definitions1077 1078When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will1079become a fold. If you don't want comments to become a fold use: >1080 :let c_no_comment_fold = 11081"#if 0" blocks are also folded, unless: >1082 :let c_no_if0_fold = 11083 1084If you notice highlighting errors while scrolling backwards, which are fixed1085when redrawing with CTRL-L, try setting the "c_minlines" internal variable1086to a larger number: >1087 :let c_minlines = 1001088This will make the syntax synchronization start 100 lines before the first1089displayed line. The default value is 50 (15 when c_no_if0 is set). The1090disadvantage of using a larger number is that redrawing can become slow.1091 1092When using the "#if 0" / "#endif" comment highlighting, notice that this only1093works when the "#if 0" is within "c_minlines" from the top of the window. If1094you have a long "#if 0" construct it will not be highlighted correctly.1095 1096To match extra items in comments, use the cCommentGroup cluster.1097Example: >1098 :au Syntax c call MyCadd()1099 :function MyCadd()1100 : syn keyword cMyItem contained Ni1101 : syn cluster cCommentGroup add=cMyItem1102 : hi link cMyItem Title1103 :endfun1104 1105ANSI constants will be highlighted with the "cConstant" group. This includes1106"NULL", "SIG_IGN" and others. But not "TRUE", for example, because this is1107not in the ANSI standard. If you find this confusing, remove the cConstant1108highlighting: >1109 :hi link cConstant NONE1110 1111If you see '{' and '}' highlighted as an error where they are OK, reset the1112highlighting for cErrInParen and cErrInBracket.1113 1114If you want to use folding in your C files, you can add these lines in a file1115in the "after" directory in 'runtimepath'. For Unix this would be1116~/.vim/after/syntax/c.vim. >1117 syn sync fromstart1118 set foldmethod=syntax1119 1120CANGJIE *cangjie.vim* *ft-cangjie-syntax*1121 1122This file provides syntax highlighting for the Cangjie programming language, a1123new-generation language oriented to full-scenario intelligence.1124 1125All highlighting is enabled by default. To disable highlighting for a1126specific group, set the corresponding variable to 0 in your |vimrc|.1127All options to disable highlighting are: >1128 :let g:cangjie_builtin_color = 01129 :let g:cangjie_comment_color = 01130 :let g:cangjie_identifier_color = 01131 :let g:cangjie_keyword_color = 01132 :let g:cangjie_macro_color = 01133 :let g:cangjie_number_color = 01134 :let g:cangjie_operator_color = 01135 :let g:cangjie_string_color = 01136 :let g:cangjie_type_color = 01137 1138CH *ch.vim* *ft-ch-syntax*1139 1140C/C++ interpreter. Ch has similar syntax highlighting to C and builds upon1141the C syntax file. See |c.vim| for all the settings that are available for C.1142 1143By setting a variable you can tell Vim to use Ch syntax for *.h files, instead1144of C or C++: >1145 :let g:filetype_h = 'ch'1146 1147NOTE: In previous versions of Vim, the following (now-deprecated) variable was1148used, but is no longer the preferred approach: >1149 :let ch_syntax_for_h = 11150 1151CHILL *chill.vim* *ft-chill-syntax*1152 1153Chill syntax highlighting is similar to C. See |c.vim| for all the settings1154that are available. Additionally there is:1155 1156chill_space_errors like c_space_errors1157chill_comment_string like c_comment_strings1158chill_minlines like c_minlines1159 1160 1161CHANGELOG *changelog.vim* *ft-changelog-syntax*1162 1163ChangeLog supports highlighting spaces at the start of a line.1164If you do not like this, add following line to your .vimrc: >1165 let g:changelog_spacing_errors = 01166This works the next time you edit a changelog file. You can also use1167"b:changelog_spacing_errors" to set this per buffer (before loading the syntax1168file).1169 1170You can change the highlighting used, e.g., to flag the spaces as an error: >1171 :hi link ChangelogError Error1172Or to avoid the highlighting: >1173 :hi link ChangelogError NONE1174This works immediately.1175 1176 1177CLOJURE *ft-clojure-syntax*1178 1179 *g:clojure_syntax_keywords*1180 1181Syntax highlighting of public vars in "clojure.core" is provided by default,1182but additional symbols can be highlighted by adding them to the1183|g:clojure_syntax_keywords| variable. The value should be a |Dictionary| of1184syntax group names, each containing a |List| of identifiers.1185>1186 let g:clojure_syntax_keywords = {1187 \ 'clojureMacro': ["defproject", "defcustom"],1188 \ 'clojureFunc': ["string/join", "string/replace"]1189 \ }1190<1191Refer to the Clojure syntax script for valid syntax group names.1192 1193There is also *b:clojure_syntax_keywords* which is a buffer-local variant of1194this variable intended for use by plugin authors to highlight symbols1195dynamically.1196 1197By setting the *b:clojure_syntax_without_core_keywords* variable, vars from1198"clojure.core" will not be highlighted by default. This is useful for1199namespaces that have set `(:refer-clojure :only [])`1200