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

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 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 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
• 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.

# 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 converts raw markdown into sections that the fixer can process.

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:

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 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 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. 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. Import it alongside parseDesign from the parser module to process 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}