Server

The [server] section configures the language server that powers the VS Code extension and other editor integrations. Adjust these settings to balance productivity features against performance on large projects.

Minimal example

[server]
hover_images = true
hover_need_refs = true
code_lenses = true
index_on_save = true
index_debounce_ms = 500

Options

code_lenses

Type: boolean (default: true)

When enabled, the editor shows inline CodeLenses above each need directive: navigation to the need’s linked code/tests, navigation to its related (parent/child) needs, and a short label for any structural gaps. Set to false to remove the lens line above every need (for example, to reduce visual clutter in dense documents).

Note

This is a project-level setting honored by any editor that drives the language server. Individual VS Code users can also toggle all CodeLenses via the built-in editor.codeLens setting.

hover_images

Type: boolean (default: true)

When enabled, hovering over image/figure directive arguments in the editor will show a preview of the image.

hover_need_refs

Type: boolean (default: true)

When enabled, hovering over need references (like :need:`REQ_001`) will show a tooltip with need information.

index_on_save

Type: boolean (default: true)

When enabled, the language server reindexes the project whenever a source document is saved, keeping cross-file features — diagnostics, need references, and the live preview’s cross-document hydration — current after every save.

Saving is debounced (see index_debounce_ms), so a burst of rapid saves coalesces into a single reindex rather than triggering one pass per save.

Set to false to index only when a document is opened (the behaviour before this default was flipped).

Note

Autosave users: with editor autosave enabled, the debounce (index_debounce_ms, default 500 ms) is what keeps a stream of automatic saves from triggering a reindex per keystroke burst. Lower it towards 0 for fresher cross-file results, or raise it to further reduce indexing work on very large projects.

index_debounce_ms

Type: integer (default: 500)

The trailing debounce window, in milliseconds, applied to save-triggered indexing (index_on_save). A save starts a reindex only after this quiet window elapses with no further save, so a burst of rapid saves (for example from editor autosave) collapses into a single pass over the latest on-disk content.

Set to 0 to disable the debounce and reindex immediately on every save. This setting only affects the save trigger — opening a document and the explicit reindex command always index immediately.

image_file_patterns

Type: array (default: extensive list of image formats)

List of glob patterns that define which files are considered images. Used for:

  • Autocompletion in image and figure directives

  • Image preview in hover tooltips

  • File discovery for image-related features

Default patterns include common formats like:

image_file_patterns = [
    "*.jpg", "*.jpeg", "*.png", "*.gif", "*.svg",
    "*.webp", "*.bmp", "*.tiff", "*.tif", "*.ico",
    "*.heif", "*.heic", "*.avif", "*.eps", "*.psd",
    "*.ai", "*.pdf"
]

Performance considerations

For large projects, consider these settings:

[server]
# Save-triggered indexing stays on, but a longer debounce window
# coalesces more saves into each reindex; set index_on_save = false
# to index only on document open instead.
index_on_save = true
index_debounce_ms = 1000

# Keep hover features for productivity
hover_images = true
hover_need_refs = true

# Limit image patterns to only used formats
image_file_patterns = ["*.png", "*.jpg", "*.svg"]