---
name: google-docs-formatting
description: Format and restructure Google Docs without changing prose; normalize heading hierarchy, create compact clickable tables of contents, and verify saved results.
version: 1.0.0
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [google-docs, formatting, headings, table-of-contents, playwright, verification]
    category: productivity
---

# Google Docs Formatting

Use this skill when the user wants an existing Google Document visually polished while preserving its wording. It covers direct browser editing, heading normalization, automatic tables of contents, and post-edit verification.

## Core contract

1. Separate **content editing** from **formatting**. If the request is formatting-only, do not change wording, punctuation, ordering, or meaning.
2. Inspect the whole document before changing styles. Infer the hierarchy from repeated structural roles, not capitalization alone.
3. Ask only when a structural boundary cannot be inferred. Examples: where a new week/chapter begins, or whether the TOC should show sections or only chapters.
4. Use the narrowest TOC depth the user requests. If they say “only Week 1 and Week 2,” include only Heading 1 rather than flattening/removing lower heading styles.
5. Verify both the visual result and the saved artifact before reporting completion.

## Recommended workflow

### 1. Preserve a baseline

- Export/download the current document as DOCX before editing when possible.
- Record a text-only checksum or extracted-text snapshot. Exclude generated TOC fields when comparing later.
- Identify the document title, major boundaries, existing heading styles, lists, and paragraph spacing.

### 2. Build a hierarchy map

Assign styles by semantic role:

- Heading 1: weeks, chapters, or other top-level divisions.
- Heading 2: assignments or major sections inside a top-level division.
- Heading 3: subsections.
- Heading 4: nested blocks inside subsections.

Keep all items with the same role at the same level and size. Watch for duplicate or partially matching titles: text search may jump to the wrong occurrence. Prefer the Google Docs outline/navigation item with its explicit `level N` label for precise targeting.

### 3. Normalize typography

- Apply a consistent body font and line spacing only if requested or clearly within scope.
- Preserve intentional emphasis, lists, links, and heading sizes unless the user asks to redesign them.
- Re-check several distant sections after global operations; selection state and cursor placement in Google Docs can be misleading.

### 4. Create or edit the TOC

- Insert a native Google Docs table of contents, not manually typed links.
- Place it at the true document start and confirm by exporting the DOCX: the TOC should appear as an `sdt` block before the first content heading.
- For a compact TOC containing only top-level divisions:
  1. Click the TOC.
  2. Open **More options → Table of contents options**.
  3. Expand **Heading levels**.
  4. Leave **Heading 1** checked.
  5. Uncheck **Heading 2**, **Heading 3**, and **Heading 4**.
  6. Refresh with **Update table of contents**.
- Do not demote or remove lower document headings merely to hide them from the TOC.

### 5. Verify

Confirm all of the following:

- Google Docs reports **Saved to Drive**.
- Exported DOCX contains the expected heading levels.
- The generated TOC includes exactly the requested entries and no extras.
- Body text is unchanged when the task was formatting-only. Compare extracted paragraph text while excluding generated TOC fields.
- The first page has no accidental insertion inside the body, duplicate TOC title, empty styled heading, or awkward page break.
- If images were requested, verify actual embedded media rather than trusting placeholders, URLs, clipboard actions, or the editor canvas. Export DOCX and inspect the ZIP for files under `word/media/`; zero media files means zero embedded images.
- Confirm each requested image appears at the intended semantic position, not merely collected at the end of the document.

### Image insertion and completion gate

1. Before editing, distinguish **text-edit permission** from **media-insertion permission**. An anonymously editable document may accept text while disabling **Insert → Image**.
2. Run a one-image probe before processing all images. Insert one image, wait for save, export DOCX, and confirm at least one file exists under `word/media/`.
3. Only after the probe succeeds should you place the remaining images and remove image placeholders.
4. Copying an image URL, pasting linked HTML, or pressing `Ctrl+V` is not proof of insertion. These operations may silently paste text, do nothing, or leave a marker.
5. If rich media insertion is unavailable, stop and report the exact partial state: text completed, images not embedded, and what access or alternate artifact is required. Do not call the document complete.
6. When the source must preserve chronology, insert each image at its original marker before deleting that marker. Verify every marker-to-image replacement individually.

See `references/image-embedding-verification.md` for deterministic DOCX checks and anonymous-editor pitfalls.

## Pitfalls

- **Find-and-style ambiguity:** searching for `Week 2` may find an internal schedule item rather than the top-level week heading. Use outline entries with level metadata or another unique contextual target.
- **Cursor is not truly at the top:** `Ctrl+Home` can act inside the current editing context. Verify placement by export or visual inspection before claiming success.
- **TOC refresh required:** changing included heading levels may update the generated block after a delay; click Update TOC or re-export and verify.
- **TOC title accidentally styled as Heading 1:** this makes the TOC list itself. Keep the title as Normal text or Title style.
- **Duplicate/blank heading:** inserting a TOC can leave an empty paragraph with a heading style. Inspect the first body elements and remove only the unintended style/blank, not document content.
- **Premature success claims:** never say formatting is complete based only on active toolbar controls. Confirm the saved state and inspect the exported document.

## Tool fallback

When direct Google APIs do not expose rich formatting operations but the document is anonymously editable, browser automation can be used. A robust Playwright recipe and DOCX verification snippets are in `references/playwright-google-docs.md`.