Konfiguracja

Plik konfiguracji projektu

Snapper szuka pliku .snapperrc.toml począwszy od bieżącego katalogu w górę aż do korzenia systemu plików. Przesłoń wyszukiwanie za pomocą --config path/to/config.toml.

Or generate one with snapper init.

Format konfiguracji

# Language for abbreviation sets (en, de, fr, is, pl)
lang = "en"

# Extra abbreviations (merged with built-in list for the selected language)
extra_abbreviations = ["GROMACS", "LAMMPS", "DFT"]

# File patterns to ignore (glob syntax)
ignore = ["*.bib", "*.cls", "*.sty"]

# Default format (overridden by --format flag)
format = "org"

# Maximum line width (0 = unlimited, overridden by --max-width flag)
max_width = 0

# Prefer breaks after independent-clause punctuation (, ; : em dash).
# With max_width = 0 this still inserts a newline after each such mark
# that is already followed by whitespace.
# clause_breaks = false

# Per-format overrides
[org]
extra_abbreviations = ["PROPERTIES", "DEADLINE"]

[latex]
extra_abbreviations = ["Thm", "Lem"]
max_width = 100
# Extra names are added to the built-in lists. Missing keys keep those lists.
# No regex `other:` matching.
verbatim_envs = ["Verbatim"]
structure_envs = ["algorithm", "comment"]
verbatim_commands = ["Verb"]

# Per-language code-block comment reflow and optional formatters.
# Used when the parser emits a Region::Code with a matching language.
# --format-code runs `formatter` on the block body after comment reflow.
[code.rust]
line_comment = "//"
block_comment = ["/*", "*/"]
formatter = ["rustfmt", "--edition", "2024"]

[code.python]
line_comment = "#"
block_comment = ["\"\"\"", "\"\"\""]
formatter = ["ruff", "format", "-"]

Pola

lang

String. Language code for the built-in abbreviation set used by the rule-based splitter. One of: en (default), de, fr, is, pl. Also selectable via --lang CLI flag.

extraabbreviations

String array. Each entry names an abbreviation that should not trigger a sentence break when followed by a period. Merged with the built-in list for the selected language. Useful for domain-specific terms your papers use frequently.

ignore

Tablica ciągów znaków ze wzorcami glob. Pliki pasujące do tych wzorców są pomijane podczas operacji --in-place i --check. Nie wpływa na tryb stdin/stdout.

format

String. Default format when auto-detection from file extension does not apply. One of: org, latex, markdown, rst, plaintext.

maxwidth

Integer. Sentences exceeding this width get wrapped at word boundaries. Set to 0 for unlimited (the default). Also respects max_line_length from .editorconfig if present.

clausebreaks

Boolean. Default: false. Also selectable via --clause-breaks.

When true, snapper inserts a soft break after independent-clause punctuation (comma, semicolon, colon, em dash, or ASCII --) that is already followed by whitespace.

  • max_width = 0 (the default): every such mark starts a new line. A sentence that is already one independent clause stays one line.

  • max_width > 0: overflowing sentences prefer those marks; a sentence that already fits stays on one line.

Tokens such as 1,000, 10:30, URLs, --flags, and unspaced dashes never split. --check uses the same mode when this flag or config is on.

longthreshold

Integer. Character threshold for advisory long diagnostics when max_width is unset. Default: 120. A long finding is never the sole cause of --check exit 1 unless --strict-long is set.

Per-format sections

Add [org], [latex], [markdown], [rst], or [plaintext] sections to override settings for specific formats.

Per-format extra_abbreviations merge with the top-level list. Per-format max_width overrides the top-level value.

The following keys are meaningful under [latex] only. Missing keys (or empty arrays) keep the built-in lists; present entries are added to those lists. There is no regex other: key (latexindent’s pattern-based extra matching is not supported).

verbatimenvs(latex)

String array of environment names treated like minted / lstlisting / verbatim / comment (Region::Code, no reflow). Built-in: minted / minted*, lstlisting / lstlisting*, verbatim, comment, Overleaf Verbatim / boxedverbatim / tcblisting / tcblisting* / codeexample / tcbverbatimwrite / tcbwritetemp / leftover tcboutputlisting / tcbexternal / dispExample / dispExample* / dispListing / dispListing*, fancyvrb BVerbatim / BVerbatim* / LVerbatim / LVerbatim* / Verbatim* / SaveVerbatim / VerbatimOut / fvextra VerbatimWrite / VerbatimBuffer / VerbEnv, verbments.sty pyglist, texments.sty / pygmentex.sty pygmented, moreverb verbatimtab / verbatimwrite / listing / listingcont / listing* / listingcont*, leftover sverb.sty verbwrite / ignore / demo / demo*, standard alltt, spverbatim.sty spverbatim, piton.sty Piton, latexindent filecontents / filecontents*, filecontentsdef.sty filecontentsdef / filecontentsgdef / filecontentsdefmacro / filecontentsgdefmacro / filecontentshere and starred twins filecontentsdef* / filecontentsgdef* / filecontentshere*, scontents.sty scontents / verbatimsc, tree-sitter-latex sagesilent / sageblock, sagetex.sty sageverbatim / sageexample / sagecommandline, pythontex.sty pycode / pycode* / pyblock / pyblock* / pyverbatim / pyverbatim* / pyconsole / pyconsole* / pygments / sympycode / sympyblock / sympyverbatim / sympyconsole / pylabcode / pylabblock / pylabverbatim / pylabconsole and starred twins, leftover default-family pyconcode / pyconverbatim / pysub / pyconsub / sympyconcode / sympyconverbatim / sympysub / sympyconsub / pylabconcode / pylabconverbatim / pylabsub / pylabconsub / pythontexcustomcode, option-family usefamily leftovers (rubycode representative; ruby / rb / julia / juliacon / jl / matlab / octave / bash / sage / rust / rs / R / Rcon / perl / pl / perlsix / psix / javascript / js), pythonhighlight.sty python, pyluatex.sty pythonq / pythonrepl, showexpl.sty LTXexample, luamplib.dtx mplibcode, luacode.sty leftover luaexec, and codehigh.sty codehigh / demohigh / codehigh* / demohigh*.

Adding an unlisted name stops reflow of that environment.

structureenvs(latex)

String array of environment names treated like equation (Region::Structure, no reflow). Built-in: the NON_PROSE_ENVS list (equation, align, tabular, tikzpicture, and starred variants, plus the built-in code envs). Figure/table chrome stays Structure; the \caption long argument is Prose. Adding algorithm stops reflow of that environment.

verbatimcommands(latex)

String array of extra command names tokenized like the built-in verb command before sentence split. The next character after the name is the delimiter. Built-in names are leftover verb / verb*, leftover lstinline, lstinputlisting, leftover spverb, leftover mintinline, inputminted, leftover mint, leftover fancyvrb Verb / Verb* / leftover SaveVerb / leftover UseVerb / leftover UseVerbatim / leftover LUseVerbatim / leftover BUseVerbatim / leftover \DefineShortVerb / \UndefineShortVerb / leftover fvextra EscVerb / leftover fvextra VerbatimInsertBuffer / VerbatimClearBuffer / InsertBuffer / IterateBuffer / VerbatimInput / BVerbatimInput / LVerbatimInput, piton.sty leftover \piton / \PitonInputFile / \PitonInputFileT / \PitonInputFileF / \PitonInputFileTF, tools/verbatim.sty \verbatiminput, tcolorbox \tcbinputlisting, pythontex.sty \inputpy / \inputpycon / \inputpylab / \inputsympy / leftover inline \py / \pyc / \pys / \pyb / \pyv / \pycon and twins / \sympy / \pylab and twins / leftover usefamily \ruby / \rb / \julia / \jl / \matlab / \octave / \bash / \sage / \rust / \rs / \R / \perl / \pl / \perlsix / \psix / \javascript / \js and twins / \inputpygments / \pygment / leftover \pythontexcustomc, pythonhighlight.sty \inputpython / \inputpythonfile / leftover \pyth, catchfilebetweentags.sty \CatchFileBetweenTags / \CatchFileBetweenDelims / \ExecuteMetaData, catchfile.sty leftover \CatchFileDef / \CatchFileEdef, moreverb \listinginput / leftover \verbatimtabinput / \verbatimtabinput* / leftover \verbatimwrite / \verbatimwrite* / leftover \listingcont, sagetex \sageinput / leftover inline \sageplot / \sagestr, scontents leftover \Scontents / \Scontents* / \typestored / \getstored / \mergesc / \meaningsc / \foreachsc; lstinline still accepts optional [...] and {...}. verb / verb* / lstinline / spverb take a delimiter or, for lstinline, optional [...] then a delimiter or {...}; following flush prose stays on its own line. mintinline / mint take optional [...], a {lang} argument, then a delimiter or {...} body; following flush prose stays on its own line. \inputminted takes the same optional [...] and {lang} then a required {filename}; following flush prose stays on its own line. SaveVerb takes optional [...], a {name} argument, then the same delimiter body as Verb; following flush prose stays on its own line. UseVerb / UseVerb* take optional [...] then a required {name}; UseVerbatim / LUseVerbatim / BUseVerbatim take optional [...] then a required {name}; following flush prose stays on its own line. leftover \DefineShortVerb takes optional [...] then a {char}; leftover \UndefineShortVerb takes a {char}; following flush prose stays on its own line. Verb takes a delimiter like verb; EscVerb takes a delimiter or {code}; following flush prose stays on its own line. \VerbatimInsertBuffer / \InsertBuffer take optional [...]; \VerbatimClearBuffer takes no args; \IterateBuffer takes optional [...] then a required {cmd}; following flush prose stays on its own line. \piton|...| is verb-like (interior .!?% stay one token); \piton{...} stays one token via the generic command argument; following flush prose stays on its own line. \lstinputlisting takes optional [...] then a required {filename}; following flush prose stays on its own line. \VerbatimInput / \BVerbatimInput / \LVerbatimInput take optional [...] then a required {filename}; following flush prose stays on its own line. \verbatiminput / \verbatiminput* take a required {filename}; following flush prose stays on its own line. \PitonInputFile takes optional <...>, optional [...], then a required {filename}; following flush prose stays on its own line. \PitonInputFileT / \PitonInputFileF take the same optional args then {file} and one extra required brace; \PitonInputFileTF takes two extra braces; following flush prose stays on its own line. \tcbinputlisting takes one required {keyval} group; following flush prose stays on its own line. \inputpy / \inputpycon take optional [...] then a required {filename}; following flush prose stays on its own line. \py / \pyc / \pys / \pyb / \pyv / \pycon and twins / \sympy / \pylab and twins take optional [...] then a delimiter or {body}; following flush prose stays on its own line. \inputpygments takes optional [...], {lang}, then a required {filename}; \pygment takes {lang} then a delimiter or {code} body; following flush prose stays on its own line. \inputpython takes required {file} {first} {last}; \inputpythonfile takes required {file} then optional [first] [last]; following flush prose stays on its own line. \pyth takes a delimiter or {code} body; following flush prose stays on its own line. \CatchFileBetweenTags takes {macro} {file} {tag}; \CatchFileBetweenDelims takes {macro} {file} {start} {end}; \ExecuteMetaData takes optional [file] then {tag}; following flush prose stays on its own line. \CatchFileDef / \CatchFileEdef take {macro} {file} {setup}; following flush prose stays on its own line. \listinginput takes optional [interval] then required {start} and {filename}; following flush prose stays on its own line. \verbatimtabinput / \verbatimtabinput* take optional [tabwidth] then a required {filename}; following flush prose stays on its own line. \verbatimwrite / \verbatimwrite* take a required {filename}; following flush prose stays on its own line. leftover \listingcont takes no args; following flush prose stays on its own line. \sageinput takes optional [...] then a required {filename}; following flush prose stays on its own line. \sageplot takes optional [ltx opts] [fmt] then a required {graphics}; \sagestr takes a required {code}; following flush prose stays on its own line. \inputsc takes optional [...] then a required {name}; following flush prose stays on its own line. \pythontexcustomc takes optional [begin|end], a required {type}, then a delimiter or {code} body; following flush prose stays on its own line. \Scontents / \Scontents* take optional [...] then a standard or verbatim arg; \typestored / \getstored / \mergesc / \meaningsc / \foreachsc take optional [...] then a required {seq}; following flush prose stays on its own line. Adding another name keeps that command’s delimited body atomic and treats an inner % as content, not a comment.

Code-block sections ([code.<lang>])

Each [code.<lang>] table configures how fenced or delimited source blocks for that language are handled. snapper init writes seed entries for common languages (rust, python, toml, lua, lisp, html, javascript).

linecomment

String. Marker for single-line comments (for example "//" or "#"). Comment text after the marker is reflowed with the sentence splitter; the marker and indentation are preserved.

A marker that repeats or decorates this one keeps its written form, so /// and //! survive a split instead of collapsing to //. A #! shebang is left alone.

Where a grammar backs the language (see grammar-backed-languages), the reflow also reaches a comment that follows code on the same line, aligning continuation sentences under the comment:

let n = 1; // First sentence.
           // Second sentence.

Without a grammar the marker must open the line. That rule keeps the // inside "// not a comment." out of the reflow.

blockcomment

String array of length two: open and close markers (for example ["/*", "*/"]). One-line and multi-line block comments are reflowed as prose between the markers.

stringdelims

String array of quote characters. Defaults to ["\"", "'"].

Without a grammar, quoting is the only thing separating a comment marker from the same characters inside a literal: a marker that trails code reflows, while the same marker inside a quoted string does not. The tracking stays conservative: an unbalanced quote, such as a Rust lifetime or an apostrophe in a shell word, makes the rest of the line read as quoted, so a marker after it goes unreflowed rather than mangled.

Grammar-backed languages ignore this field; the parse already knows which bytes belong to a string.

escape

String holding one character that escapes the next inside a string literal. Defaults to a backslash.

formatter

String array treated as argv for std::process::Command. Only runs when the CLI flag --format-code is set. Missing binaries, non-zero exits, and a ~30s watchdog timeout each leave the reflowed body in place (non-fatal).

If a language has no [code.<lang>] entry (or the fence has no language), the block body passes through unchanged aside from normal trailing-newline preservation.

Grammar-backed languages

The treesitter feature, on by default, parses code blocks in rust, python, javascript, c, cpp, go, bash and html to tell a comment from a string. Fence aliases resolve as well: rs, py, js, sh.

A build feature governs this, not a config field, and a [code.<lang>] entry remains required. The grammar decides which bytes form a comment; the entry supplies the markers used to re-emit it.

Two builds carry no grammars and fall back to the scanner for every language:

  • wasm32-unknown-unknown, the target behind the Obsidian and Word integrations, where the C runtime and its grammars would need a wasm libc.

  • Any build configured with --no-default-features that does not opt back in.

The VS Code extension runs the CLI rather than the wasm build, so it has grammars.

The scanner reads field-string-delims to find trailing comments on its own, so both engines agree on ordinary code. A grammar still wins on raw strings, heredocs, triple-quoted strings and nested comments, where quote counting alone gives the wrong answer.

Block comments stay on the scanner. A close marker inside a string does not end the comment, so let s = "*/"; in a /* ... */ block stays in the comment. When the closer is itself a quote sequence (""", '''), the first match is the closer, which is how Python docstrings reflow.

Kolejność priorytetów

CLI flags override config file values. Per-format sections override top-level config values. Config file values override .editorconfig values. .editorconfig overrides built-in defaults.