# Google Docs heading hierarchy and automatic TOC

Use this after confirming the document's semantic structure. The key rule is: normalize heading levels before inserting or refreshing the table of contents.

## 1. Build and verify the hierarchy

Create an explicit level map, e.g.:

- Heading 1: weeks / parts
- Heading 2: assignments / main sections
- Heading 3: blocks within an assignment
- Heading 4: nested subsections

Export DOCX and inspect each paragraph's `w:pStyle` in `word/document.xml`. This catches hierarchy errors that are easy to miss visually.

Google Docs exposes outline entries as elements such as:

```html
<div class="navigation-item-content-container"
     aria-label="Section name level 3">
```

Use the exact outline entry to navigate when text fragments are duplicated. Search-based formatting can hit the wrong heading when one heading is a substring of another (for example, a product name nested inside a longer title).

After navigating to the exact heading, focus the hidden editor iframe and apply the semantic style shortcut:

```js
const frame = page.locator('iframe.docs-texteventtarget-iframe').first();
await frame.focus();
await page.keyboard.press('Control+Alt+1'); // Heading 1
await page.keyboard.press('Control+Alt+2'); // Heading 2
await page.keyboard.press('Control+Alt+3'); // Heading 3
await page.keyboard.press('Control+Alt+4'); // Heading 4
await page.keyboard.press('Control+Alt+0'); // Normal text
```

Verify the serialized `w:pStyle` values in a fresh DOCX export rather than trusting the toolbar alone.

## 2. Insert an automatic linked TOC

Put the cursor at the true start of the document. In Docs, keyboard `Ctrl+Home` may act inside the current editing context; verify placement by exporting and checking the first body children.

Menu path:

`Insert → Page elements → Table of contents → links style`

The links-style palette option may expose:

```text
Row 1. Column 3. Table of contents with blue links and no page numbers
```

If adding a visible title such as `ОГЛАВЛЕНИЕ`, style it as Normal text with direct visual formatting so it does not appear inside its own TOC.

A DOCX export represents the automatic TOC as an `w:sdt` content-control block. Verify that it is near the beginning of `w:body` and that it contains both major parts/weeks and their requested sections.

## 3. Refresh after hierarchy changes

Click inside the TOC. A compact floating toolbar appears with a button whose accessible label is:

```text
Update table of contents
```

Click that button only after all heading styles are final. Then wait for `Document status: Saved to Drive.` and re-export.

## 4. Final checks

- Outline levels match the intended semantic map.
- Same-level headings serialize to the same `HeadingN` style.
- The TOC is at the intended location and is an actual automatic block, not manually typed links.
- Both top-level parts/weeks and requested assignments occur in the TOC text.
- The TOC title is not listed inside itself.
- Original body wording is unchanged; generated TOC content and an explicitly authorized TOC title are excluded from the strict original-text comparison.
- Saved status is visible and a fresh export contains the final hierarchy.

## Pitfalls

- Do not claim the TOC is correctly placed from a screenshot alone; inspect `w:body` order in the export.
- Do not use broad text search for duplicate/sub-string headings; target the exact outline entry.
- Do not insert the TOC before finalizing heading levels, because it immediately becomes stale.
- A selected TOC may visually resemble ordinary links. The `w:sdt` block and update toolbar are stronger proof that it is automatic.