Configuration
Put a badness.toml file at the root of your project to share formatting and linting settings between the CLI and language server. Every key is optional and spelled in kebab-case. Badness reports an error for an unknown key or section. This guide covers common setup tasks; the configuration reference lists all keys, defaults, and accepted values.
Create a project config
Run this in a project that does not yet have a badness.toml:
badness initThe starter file contains commented defaults and examples. A small active configuration might look like this:
extend-exclude = ["vendor/", "build/"]
[format]
line-width = 100
wrap = "sentence"
[lint]
ignore = ["dollar-display-math"]Commit the file so contributors use the same settings. Add #:schema https://badness.dev/badness.schema.json at the top for completion and validation in editors that support TOML schema directives. See editor support for other ways to associate the schema.
Choose the configuration source
For each input, Badness walks from the file’s directory upward and uses the first badness.toml it finds. The walk stops at a directory containing a .git entry (the repository root), so a config file outside your repository is never picked up.
If no project file is found, Badness next checks the BADNESS_CONFIG environment variable. When set (and non-empty), it names a config file to use instead of the global user config below—handy for keeping one config on a synced drive and pointing every machine at it. A set BADNESS_CONFIG shadows the global config entirely.
If BADNESS_CONFIG is unset, Badness falls back to a global user config: the first existing file among
$XDG_CONFIG_HOME/badness/config.toml~/.config/badness/config.toml- the platform config directory (
%APPDATA%\badness\config.tomlon Windows,~/Library/Application Support/badness/config.tomlon macOS)
The BADNESS_CONFIG and global files use the same schema as a project badness.toml and are whole-file fallbacks, never merged with a project config. Relative exclude patterns in them resolve against the working directory (CLI) or the document’s directory (language server) rather than the config’s own directory. The language server uses the same resolution, so both are easy ways to set editor-wide defaults such as wrap = "preserve" (an edit is picked up when the server restarts). If none of these files is found, built-in defaults apply.
Two global CLI flags override discovery:
--config <PATH>uses that file instead of discovering one.--no-configignores any project,BADNESS_CONFIG, or global file and uses built-in defaults.
CLI flags for individual options (--line-width, --wrap, --select, etc.) override the corresponding config values for a single run.
To choose a file explicitly or try the built-in defaults:
badness --config path/to/badness.toml format paper.tex
badness --no-config lint paper.texEditor support
Badness publishes a JSON Schema for badness.toml so editors with TOML support can provide key and value completion, hover documentation, and validation.
Schema URL: https://badness.dev/badness.schema.json
The schema is generated from the configuration types and checked against them in the test suite. The version at the URL tracks the latest released version of Badness.
VS Code (Even Better TOML)
With the Even Better TOML extension installed, add this association to your user or workspace settings.json:
{
"evenBetterToml.schema.associations": {
"^(.*/)?badness\\.toml$": "https://badness.dev/badness.schema.json"
}
}Inline #:schema directive
TOML tools that support inline schema directives can select the schema from the configuration file itself:
#:schema https://badness.dev/badness.schema.jsonThis is also useful for the global user configuration, whose generic config.toml file name should not be associated with Badness automatically.
Other editors
Any editor or language server that consumes JSON Schemas—including Helix, Neovim with taplo-lsp, Zed, and IntelliJ—can use the same URL through its TOML schema settings.
Share settings between projects
Use extend to inherit another file and override the settings this project needs:
extend = "../shared/badness.toml"
[format]
line-width = 100The path is relative to the file that declares it. Tables merge by key, and the project’s values override inherited values. extend-exclude adds patterns to inherited exclusions, and [lint] extend-select adds to inherited rule lists. See the inheritance reference for the other merge rules.
Exclude files
Use extend-exclude to add gitignore-style patterns without replacing the built-in exclusions:
extend-exclude = ["vendor/", "generated/"]Both the formatter and linter apply these patterns when walking directories. They still process files named explicitly. Add --force-exclude when a runner passes filenames that should respect the exclusions:
badness format --force-exclude generated/tables.texUse exclude to replace the default list entirely. For an exception within a document, use the directives in the formatting and linting guides.
Adjust formatting and linting
Use [format] for layout and [lint] for rule selection. The formatting and linting guides show the usual workflows. The reference also covers build paths, custom commands, and environments when a LaTeX project needs additional context.
The dprint plugin uses dprint.json and does not load badness.toml.
Machine-specific settings, such as TEXMF-tree discovery and the PDF viewer, belong in your editor’s LSP settings rather than a shared badness.toml. See editor configuration.