# How to Use the Fixer to Automatically Correct Section Order in DESIGN.md Files

> Learn how to use the Instagit fixer to automatically correct section order in DESIGN.md files. This tool efficiently sorts known sections by parsing and applying canonical order for cleaner documentation.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The Instagit fixer reorders sections in DESIGN.md files by parsing the document into a `FixerInput`, separating known sections from unknown ones, and sorting the known sections according to the `CANONICAL_ORDER` array defined in the section-order rule.**

The fixer is a core component of the Instagit linter that enforces canonical structure in [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files. Whether you are maintaining a single design document or automating checks across a repository, understanding how to leverage the automatic section correction ensures your documentation follows the project's style guide consistently.

## How the Fixer Reorders Sections

The fixer implementation lives in [`packages/cli/src/linter/fixer/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/fixer/handler.ts) and processes documents through a three-step algorithm that preserves front-matter while enforcing canonical structure.

### Step 1: Identify the Prelude

The fixer first locates the **prelude**—the leading empty-heading section that typically contains front-matter. This section is always preserved at the beginning of the document regardless of the canonical order.

### Step 2: Separate Known and Unknown Sections

The fixer divides remaining sections into two categories:

- **Known sections**: Headings (or their aliases) that appear in `CANONICAL_ORDER`, defined in [`packages/cli/src/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/rules/section-order.ts)
- **Unknown sections**: Custom headings not defined in the canonical list

Unknown sections are preserved in their original order and appended after the sorted known sections.

### Step 3: Sort and Recombine

The fixer sorts known sections according to the `CANONICAL_ORDER` array, then recombines the document: **prelude → sorted known → unknown**. The result is emitted as `fixedContent` alongside a `details` object containing the before and after heading order for verification.

## Using the CLI to Fix Section Order

The `instagit lint` command accepts a `--fix` flag that triggers the automatic correction. When present, the linter calls `fixSectionOrder` internally and writes the corrected content back to the file.

```bash

# Lint a DESIGN.md file and automatically rewrite it with the correct section order

instagit lint path/to/DESIGN.md --fix

```

If you omit the `--fix` flag, the linter only reports violations without modifying the file.

## Programmatic API for Custom Workflows

For integration into custom build scripts or CI pipelines, import the fixer directly from `@instagit/cli` and run it on parsed documents. The parser in [`packages/cli/src/linter/parser/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/handler.ts) converts raw markdown into sections that the fixer can process.

```ts
import { readFile } from 'fs/promises';
import { parseDesign } from '@instagit/cli/src/linter/parser/handler';
import { fixSectionOrder } from '@instagit/cli/src/linter/fixer/handler';

async function autoFix(file: string) {
  const raw = await readFile(file, 'utf8');
  const { sections } = parseDesign(raw);
  const { fixedContent, details } = fixSectionOrder({ sections });

  console.log('Before order:', details.beforeOrder);
  console.log('After order :', details.afterOrder);
  await Deno.writeTextFile(file, fixedContent);
}

autoFix('examples/totality-festival/DESIGN.md');

```

The `fixSectionOrder` function accepts a `FixerInput` object containing the parsed sections and returns an object with `success`, `fixedContent`, and `details` properties.

## Debugging and Inspection

To verify what changes the fixer applied without writing to disk, inspect the `details` object returned by the function:

```ts
const result = fixSectionOrder({ sections });
console.log('Reordered headings:', result.details.afterOrder);
console.log('Original headings:', result.details.beforeOrder);

```

This output is useful for generating migration reports or validating that the canonical order matches your project's expectations before applying fixes.

## Summary

- The fixer resides in [`packages/cli/src/linter/fixer/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/fixer/handler.ts) and implements the `fixSectionOrder` function
- It preserves the prelude (front-matter), sorts known sections by `CANONICAL_ORDER`, and appends unknown sections unchanged
- Invoke via CLI using `instagit lint path/to/DESIGN.md --fix`
- Use the programmatic API by importing `fixSectionOrder` and `parseDesign` from `@instagit/cli`
- The canonical order is defined in [`packages/cli/src/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/rules/section-order.ts) and can be customized by modifying that file

## Frequently Asked Questions

### What happens to sections not in the canonical order?

Unknown sections—headings that do not match any entry in `CANONICAL_ORDER`—are left untouched and appended after all sorted known sections. This preserves custom documentation while standardizing the core structure.

### Where is the canonical section order defined?

The `CANONICAL_ORDER` array is defined in [`packages/cli/src/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/rules/section-order.ts). This file also contains heading aliases that map alternative titles to canonical names. Updating this list changes the ordering applied by the fixer across all operations.

### Can I use the fixer without the CLI?

Yes. The fixer is exposed as a programmatic API through `fixSectionOrder` in [`packages/cli/src/linter/fixer/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/fixer/handler.ts). Import it alongside `parseDesign` from the parser module to process [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) content in Node.js or Deno environments without invoking the command line.

### Does the fixer modify the file content or create a backup?

The fixer returns corrected content via the `fixedContent` property but does not automatically write to disk. When using the CLI with `--fix`, the linter writes the corrected content back to the original file. When using the API, you must explicitly handle file I/O using `Deno.writeTextFile` or your preferred filesystem method.