# Text Structure Normalization / Formatting

IWE provides auto-formatting through the LSP formatting feature. This typically triggers when you save your document (if your editor is configured for format-on-save) or manually via a formatting command.

## What Gets Normalized

### 1. Link Title Updates

Link titles are automatically updated to match the header of the linked document.

**Before:**

``` markdown
See [old title](my-note) for details.
```

**After** (if `my-note.md` has header "# My Updated Note"):

``` markdown
See [My Updated Note](my-note) for details.
```

### 2. Header Level Adjustment

Header levels are adjusted to maintain a proper tree structure. This ensures that nested sections have correct relative header levels.

**Before:**

``` markdown
# Main Document

#### Incorrectly Deep Section

Some content.
```

**After:**

``` markdown
# Main Document

## Incorrectly Deep Section

Some content.
```

### 3. Ordered List Numbering

Ordered lists are renumbered sequentially, regardless of the original numbers.

**Before:**

``` markdown
1. First item
5. Second item
3. Third item
```

**After:**

``` markdown
1. First item
2. Second item
3. Third item
```

### 4. List Indentation and Spacing

List structure is normalized with consistent indentation and proper newlines.

**Before:**

``` markdown
- Item one
    - Badly indented
  - Inconsistent
-No space after marker
```

**After:**

``` markdown
- Item one
  - Badly indented
  - Inconsistent
- No space after marker
```

### 5. Whitespace Cleanup

Excess blank lines and trailing whitespace are cleaned up.

## Usage

### Format on Save

Most editors can be configured to format on save:

- **VS Code**: Enable "Format On Save" in settings
- **Neovim**: Configure autocommand or use plugin like `conform.nvim`
- **Helix**: Set `auto-format = true` in `languages.toml`

### Manual Formatting

Trigger formatting manually:

- **VS Code**: `Shift+Alt+F` / `Shift+Option+F`
- **Neovim**: `:lua vim.lsp.buf.format()`
- **Helix**: `:format`

## Configuration

Link title updates, header level adjustment, list renumbering, and whitespace cleanup are always part of formatting and cannot be toggled individually. The markdown syntax used in the formatted output is configurable in `.iwe/config.toml`.

### Custom Formatting Tokens

You can customize the markdown syntax used during formatting. For example, to use underscores for emphasis and plus signs for lists:

``` toml
[markdown.formatting]
emphasis_token = "_"
strong_token = "__"
list_token = "+"
```

See [Configuration](configuration.md) for all available formatting options.

## Tips

- **Enable format-on-save** for consistent formatting across your library
- **Use with version control** to easily review formatting changes
- If you notice unexpected formatting, check [Header Levels Normalization](feature-normalization.md) for detailed header adjustment rules
