google-docs

# Google Docs authoring ## Locate text, never compute indexes (the #1 source of bugs) Docs edits address zero-based UTF-16 index ranges within one tab, and every write SHIFTS later indexes. Guessed or stale indexes silently hit the wrong paragraphs - the classic symptom is two lists merging into one continued numbering. The tools remove the need for index math: - `find_text` returns FRESH `{start, end}` ranges for exact text - the direct source of indexes for `apply_text_style`, `apply_paragraph_style`, `delete_content`, and `set_paragraph_format`. Locate, then edit, in back-to-back calls. - `create_list` takes `firstItemText`/`lastItemText` anchors and resolves the range itself: name the first and last item paragraphs and no index ever touches your hands. Use one `create_list` per list with the right preset (BULLET_* for bullets, NUMBERED_* for numbers); never stretch one call across two visually separate lists. When a range must come from structure instead of a phrase (styling a whole paragraph, addressing a table), read it from `read_document` elements: a paragraph's `{start, end}` is the range for paragraph-level tools. END IS EXCLUSIVE: one short misses the last character, one long styles the character after the phrase (the classic italic-or-link off-by-one). When raw indexes are unavoidable: `read_document` first, compute ONE edit, pass `requiredRevisionId`, apply, and re-read before the next positional edit. Order multi-part positional work BACK-TO-FRONT (highest index first) when re-reading between steps is too expensive; earlier ranges stay valid. ## Creating a document `create_document` makes a BLANK doc (its API ignores content), so plan: - Content known up front: prefer google-drive `google_drive_create_file` with Markdown (`target_mime_type: ...document`), which imports headings, lists, and tables in one call and can target a folder. - Building incrementally: `create_document`, then `insert_text` with `index` omitted to APPEND each paragraph; append mode reads the tail itself and is revision-guarded automatically. `paragraphStyle` styles the new paragraphs and `bold`/`italic` style the inserted text in the same call, so a well-structured document is a sequence of appends with no styling pass. - Doc creates cannot set a parent folder. When placement matters, create and then google-drive `google_drive_move_or_rename` with `destination_folder_id`. ## Structure is not optional A document without hierarchy reads as a text dump. Default shape for any report/memo/notes request: a TITLE paragraph, an italic byline or date line, HEADING_2 per section, short body paragraphs with bold on the phrases that matter, and bulleted lists for enumerations. Use `insert_text`'s paragraphStyle/bold/italic arguments as you write rather than styling afterwards. ## Styling - Character styling (`apply_text_style`): bold/italic/underline/strike, fontSize, fontFamily, textColor/backgroundColor as `#RRGGBB`, linkUrl. Exclusive END index: to style one paragraph without its trailing newline, use `end - 1` from the read. - Paragraph styling: `apply_paragraph_style` for named styles (TITLE/HEADING_1..6), `set_paragraph_format` for alignment, indents, and line spacing (percent, 100 = single). - Lists: `create_list` over the paragraphs' range; each newline-separated paragraph becomes one item. Insert the plain lines first, then bullet them. - The preset is part of correctness: enumerations get a BULLET_* preset by default; NUMBERED_* only when the content is ordered (steps, rankings) or the request says numbered. - Before bulleting, check the read for paragraphs that ALREADY show a leading bullet - text appended directly after a list inherits its membership, and `create_list` over such paragraphs restyles the ORIGINAL list, continuing its numbering (a second list showing 4, 5, 6). Strip first: `create_list` with `remove: true` over exactly the new paragraphs, then apply the wanted preset. ## Tables and images - `insert_table` inserts an EMPTY grid. To fill it: re-read (cells appear with their own index ranges) and `insert_text` into cells from the LAST cell to the first, so earlier cell indexes stay valid. - Style a table AFTER filling it, addressing it by the table element's `start` from `read_document`: `set_table_cell_shading` the header row (pick the row's text color against that fill), `merge_table_cells` for a title cell spanning columns (top-left content survives, the rest is dropped), `set_table_column_width` for fixed widths in points. Structural edits (merge) shift indexes: re-read before further text edits. - `insert_image` needs a PUBLICLY fetchable URL (Google fetches it; auth walls and private hosts fail), PNG/JPEG/GIF. Size with width/height in points (aspect kept when only one is set). - `insert_page_break` starts a new page at an index. ## Headers and footers `set_header_footer` sets the default header or footer in one call: it creates the segment when the doc has none, replaces the text otherwise, and empty text clears it. The text is static (no page-number fields exist in the API); it applies to the first tab. Never `insert_text` a fake header into the body - it scrolls away with the content. ## Bulk text ops `replace_text` replaces literal strings everywhere (or in named tabs) with no index math; prefer it for renames and corrections. `delete_content` rejects ranges that split table structure or surrogate pairs; deleting a paragraph's final newline merges it with the next. ## Verify your work Re-read with `read_document` for structure and styles, or google-drive `google_drive_read_file` for the whole doc as Markdown, or `google_drive_export_file` (pdf) when the visual result matters. After any styling call, confirm the styled span covers exactly the intended text before moving on.