Formatting

The [format_rst] section configures the reStructuredText formatter, which can automatically format and clean up your RST files. Use this to enforce consistent indentation, line lengths, and list styles across your project.

Minimal example

[format_rst]
paragraph_line_length = 88
paragraph_semantic_wrap = true
validate = true

Core options

fail_on_warning

Type: array (default: [])

List of linting codes that should cause formatting to fail. This is useful in CI/CD pipelines to enforce code quality.

fail_on_warning = ["rst.invalid_code_block", "rst.malformed_table"]
validate

Type: boolean (default: true)

When true, the formatter validates that the document structure hasn’t changed after formatting. This prevents accidental content corruption.

Indentation settings

blockquote_indent

Type: integer (default: 2)

Number of spaces to indent blockquotes.

This is a paragraph.

  This is a blockquote, indented 2 spaces.
definition_list_indent

Type: integer (default: 2)

Number of spaces to indent definition bodies in definition lists.

Term
  Definition body indented 2 spaces.
directive_indent

Type: integer (default: 3)

Number of spaces to indent directive content.

.. note::
   This content is indented 3 spaces.
field_list_indent

Type: integer (default: 2)

Number of spaces to indent field list bodies.

:Author: John Doe
  Second line indented 2 spaces.
literal_indent

Type: integer (default: 2)

Number of spaces to indent literal blocks after paragraphs.

This is a paragraph::

  This literal block is indented 2 spaces.
substitution_indent

Type: integer (default: 3)

Number of spaces to indent substitution definition content.

.. |name| replace::
   Substitution content indented 3 spaces.

List formatting

enum_list_auto

Type: string (default: "preserve")

Controls behaviour of enumerated lists with auto # markers:

  • "preserve": Keep original auto markers from source

  • "always": Always use auto markers for subsequent items

  • "never": Never use auto markers for subsequent items

enum_list_style

Type: string (default: "preserve")

Controls the style of enumerated list markers:

  • "preserve": Keep original style from source

  • "period": Use periods (1., 2., 3.)

  • "rparen": Use right parenthesis (1), 2), 3))

  • "parens": Use parentheses ((1), (2), (3))

Field list formatting

field_list_align_body

Type: boolean (default: false)

When true, align field list body continuation lines with the first line.

# When false (default):
:Field: This is the body
  and this continues on next line.

# When true:
:Field: This is the body
        and this aligns with first line.
field_list_body_on_new_line

Type: integer (default: 20)

Field name length threshold. When a field name exceeds this length, the body starts on a new line.

:Short: Body on same line.

:This is a very long field name:
  Body starts on new line due to length.

Paragraph formatting

paragraph_line_length

Type: integer or null (default: null)

Target line length for paragraph wrapping. When set, paragraphs are wrapped at word boundaries near this length. Not a hard limit and won’t wrap paragraphs in tables.

paragraph_line_length = 88  # Wrap paragraphs around 88 characters
paragraph_semantic_wrap

Type: boolean (default: false)

When true, wrap paragraphs at semantic boundaries rather than arbitrary line lengths:

  • Always wrap at sentence boundaries ([.!?] [A-Z])

  • May also wrap at clause boundaries ([,;]) if paragraph_line_length is set

# With semantic wrapping:
This is a sentence.
This is another sentence with a clause,
and here's the rest.

Table formatting

simple_table_space

Type: integer (default: 2)

Number of spaces between columns in simple tables.

====  ====  ====
A     B     C
====  ====  ====
1     2     3
====  ====  ====

Transition formatting

transition_char

Type: string or null (default: null)

Character to use for transition lines. When null, preserves original characters.

Available options: "-", "=", "~", "^", ".", "+", "_", "#"

transition_length

Type: integer (default: 10)

Length of transition lines in characters.

--------  # 8 character transition with "-"