Jump to: Description / Requirements / Installation / Configuration / Troubleshooting / To do / Links
TEXMagic is a very simple Neovim plugin that facilitates LaTeX build engine selection via magic comments. It is designed with the TexLab LSP server's build service in mind, which at the time of this plugin's making had to be specified globally in init.lua
/vim
(with the help of the Neovim team's lspconfig plugin) and could not be set on a by-project basis.
The plugin identifies magic comments at the very top of a LaTeX document (as below) and will currently only extract magic TeX program comments, which specify the name of a build "engine" or toolchain.
%! TEX program = xelatex
The plugin looks in two places for the engine name requested in the magic comment:
init.lua
/vim
(via the setup
function).The plugin provides three default latexmk
build engines: pdflatex
, xelatex
, and dvipspdf
. In order to be used, the setup
function must be called in init.lua
/vim
. The user can also provide any number of custom build engines (see instructions).
Currently, anyone who wishes to use TexLab's build service can only specify a global build engine, which is troublesome if you need different build engines for different projects. This plugin is mainly for people who would like to use TexLab's build service and would like to make it a little more configurable. Vimtex is more functional than the TexLab LSP server, but anyone not using Vimtex for whatever reason should find TeXMagic.nvim useful.
g:texflavor
to latex
.vim.g['tex_flavor'] = 'latex'
let g:tex_flavor = 'latex'
Install using your preferred package manager.
For the default build engines to be available, you must call the setup function in your init.lua
/vim
. Once it is called, the global variable _G.TeXMagicBuildConfig
becomes available and can be used to value the build
key in your TexLab LSP server config.
use({'jakewvincent/texmagic.nvim',
config = function()
require('texmagic').setup({
-- Config goes here; leave blank for defaults
})
end
})
require('paq')({
-- Your other plugins;
'jakewvincent/texmagic.nvim';
-- Your other plugins;
})
-- Include the setup function somewhere else in your init.lua file, or the
-- plugin won't activate itself:
require('texmagic').setup({
-- Config goes here; leave blank for defaults
})
" Vim-Plug
Plug 'jakewvincent/texmagic.nvim'
" NeoBundle
NeoBundle 'jakewvincent/texmagic.nvim'
" Vundle
Bundle 'jakewvincent/texmagic.nvim'
" Pathogen
git clone https://github.com/jakewvincent/texmagic.nvim.git ~/.vim/bundle/texmagic.nvim
" Dein
call dein#add('jakewvincent/texmagic.nvim')
" Include the setup function somewhere else in your init.vim file, or the
" plugin won't activate itself:
lua << EOF
require('texmagic').setup({
-- Config goes here; leave blank for defaults
})
EOF
You can pass nothing to the setup function, in which case the default build engines are made available and can be selected if their name matches the program name specified in a magic comment.
-- Only default build engines made available (pdflatex, xelatex, dvipspdf)
require('texmagic').setup{}
The user can also specify different build engines. If these have the same name as any of the default build engines, TeXMagic will prioritize those over the defaults. There must be a key named 'engines' in your config table.
-- Run setup and specify two custom build engines
require('texmagic').setup{
engines = {
pdflatex = { -- This has the same name as a default engine but would
-- be preferred over the same-name default if defined
executable = "latexmk",
args = {
"-pdflatex",
"-interaction=nonstopmode",
"-synctex=1",
"-outdir=.build",
"-pv",
"%f"
},
isContinuous = false
},
lualatex = { -- This is *not* one of the defaults, but it can be
-- called via magic comment if defined here
executable = "latexmk",
args = {
"-pdflua",
"-interaction=nonstopmode",
"-synctex=1",
"-pv",
"%f"
},
isContinuous = false
}
}
}
After calling the setup function, interface your nvim-lspconfig TeXLab setup with TeXMagic using the global variable _G.TeXMagicBuildConfig
. If I'm using TexLab's build service and want to allow the build engine to vary based on my magic comments, I'll use _G.TeXMagicBuildConfig
to value the build
key in my TexLab config table (such as below).
require('lspconfig').texlab.setup{
cmd = {"texlab"},
filetypes = {"tex", "bib"},
settings = {
texlab = {
rootDirectory = nil,
-- ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
build = _G.TeXMagicBuildConfig,
-- ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑
forwardSearch = {
executable = "evince",
args = {"%p"}
}
}
}
}
tex
document but has no magic comment on open ⇒ Default build engine is selected (pdflatex)tex
document and did have a magic comment on open ⇒ The named build engine is selected from the custom build engines or the default build engines (or if it is in neither of those, pdflatex is selected as the build engine)A few vim functions are defined that may help diagnose problems:
TeXMagicShowComments
: returns any magic comments found at the top of your documentTeXMagicCommentsFound
: returns a boolean indicating whether or not magic comments were foundTeXMagicSetupStatus
: returns a boolean indicating whether TeXMagic's setup function was runTeXMagicSelectedProgram
: returns the name and source of the selected TeX program (if any was selected)TeXMagicConfigFound
: returns a boolean indicating whether any user-provided build engines were foundTeXMagicLoaded
: returns the status of the plugin (if loaded, returns 1
)