Format

Formatting

LaTeX Workshop provides both LaTeX and BibTeX formatting capabilities. The former depends on external tools like latexindent or tex-fmt. The latter is provided by the grammar parsing tool embedded in this extension.

LaTeX files

LaTeX Workshop can invoke your installed latexindent or tex-fmt to format the whole LaTeX file or a part of it. Calling which formatter is set by config latex-workshop.formatting.latex, which can take three values: none for not using any formatter, latexindent and tex-fmt per se.

Please note that you need to first ensure installing these formatters, otherwise the formatting will fail. This should not cause unexpected data loss, though.

Relevant settings

latex-workshop.formatting.latex

Define the program to format the LaTeX document.

type	default value
string	"none"

The possible values are: "none", "latexindent", or "tex-fmt".

latex-workshop.formatting.latexindent.path

Define the path of the latexindent executable. If latexindent is in the PATH, setting this variable to the executable name is fine.

type	default value
string	"latexindent"

latex-workshop.formatting.latexindent.args

Define the command line arguments for latexindent. In the addition to the placeholders defined for recipes, the following placeholders are accepted

• %TMPFILE%: The full path of the raw TeX file to be formatted. At this moment you need to use it as an input file of latexindent.
• %INDENT%: The indent character of the file, typically \t, ' ', ' '.

Note: For the moment the -c option requires trailing slash."

type	default value
Array of strings	[ "-c", "%DIR%/", "%TMPFILE%", "-y=defaultIndent: '%INDENT%'" ]

latex-workshop.formatting.tex-fmt.path

Define the path of the tex-fmt executable. If tex-fmt is in the PATH, setting this variable to the executable name is fine.

type	default value
string	"tex-fmt"

latex-workshop.formatting.tex-fmt.doNotWrap

Do not wrap the output of tex-fmt. This setting adds --keep flag to tex-fmt. Turning this off may wrap magic comments, and/or has unintended side effects.

Type	Default Value
boolean	true

Bibtex files

BibTeX files can be formatted either by using the VSCode Format Document or Format Selection commands or by calling one of the following three commands

• latex-workshop.bibsort: to sort the file,
• latex-workshop.bibalign: to align fields,
• latex-workshop.bibalignsort: to perform both at once.

These commands can be accessed through Visual Studio Code's Command Palette (default ctrl+shift+p or ⌘+shift+p).

Whether to sort the file when calling VSCode formatting commands is set by latex-workshop.bibtex-format.sort.enabled. When formatting bibtex entries, you can decide to keep the trailing comma of the last field in each entry by setting latex-workshop.bibtex-format.trailingComma to true

Sorting entries

latex-workshop.bibtex-format.sortby

The commands latex-workshop.bibsort and latex-workshop.bibalignsort will sort a .bib file according to an array of sorting keys specified in latex-workshop.bibtex-format.sortby. Valid keys are either a bibtex field name (title, author, year, etc.), or \"year-desc\" to sort by year in descending order, or \"key\" for the entry key, or \"type\" for the entry type (article, book, misc, etc.). E.g. [\"author\", \"year-desc\", \"title\"].". For example, set this to ["author", "year-desc", "title"] to sort by author, then year in descending order, then title

Type	Default Value
array of strings	[ "key" ]

latex-workshop.bibtex-format.handleDuplicates

When sorting BibTeX files, how to handle duplicates that appear. Duplicates are decided by latex-workshop.bibtex-format.sortby.

Type	Default Value	Possible Values
enum of string	"Highlight Duplicates"	"Ignore Duplicates", "Highlight Duplicates", "Comment Duplicates"

latex-workshop.bibtex-format.sort.enabled

Sort content when calling VSCode formatter on a .bib file.

Type	Default Value
boolean	false

latex-workshop.bibtex-entries.first

When latex-workshop.bibtex-fields.sort.enabled is true, these fields are put at the top, in the order defined by the array.

Type	Default Value
array of strings	[ "xdata", "string" ]

Aligning fields

The commands latex-workshop.bibalign and latex-workshop.bibalignsort provide basic alignment of bibliography entries. This action can be configured through the following options.

latex-workshop.bibtex-format.tab

What kind of indentation to use before each field.

Type	Default Value
string	"2 spaces"

The possible values are: "tab", "X spaces" or simply "X" where X is a number.

latex-workshop.bibtex-format.align-equal.enabled

Align equal signs inside each entry.

Type	Default Value
boolean	true

latex-workshop.bibtex-format.surround

Whether to surround each field value in quotation marks or curly braces.

Type	Default Value	Possible Values
enum of string	"Curly braces"	"Curly braces", "Quotation marks"

latex-workshop.bibtex-format.case

Whether to use upper- or lowercase field names. (E.g. AUTHOR = ... vs author = ...).

Type	Default Value	Possible Values
enum of string	"lowercase"	"UPPERCASE", "lowercase"

latex-workshop.bibtex-format.trailingComma

Keep the trailing comma of the last field item.

Type	Default Value
boolean	false

Sorting fields

latex-workshop.bibtex-fields.sort.enabled

Sort fields inside every entry. The sorting order is defined by latex-workshop.bibtex-fields.order. This variable only has effect when formatting bibtex aligns fields. It is not possible to sort entries without aligning them.

Type	Default Value
boolean	false

latex-workshop.bibtex-fields.order

When latex-workshop.bibtex-fields.sort.enabled is true, sort fields according the order defined here and then alphabetically for not listed fields."

Type	Default Value
array of strings	[ ]