This section describes behaviors that you need to understand when you edit documents using the Docs API.
In general, you cannot execute edits that will result in invalid structure of elements within a document. See the reference documentation for each request type under the BatchUpdate method for constraints and rules that apply to those request types. The sections below summarize the key rules across those methods.
Inserting text and inline images
- These objects must be inserted within the bounds of an existing Paragraph. For instance, text cannot be inserted at a table's start index.
- The API may implicitly adjust the location to prevent insertions within Unicode grapheme clusters. When this happens, the text is inserted immediately after the grapheme cluster.
Applying formatting text
- When you apply paragraph-level formatting to a range, the formatting is applied to any paragraph that is partially or completely overlapped by that range.
- The range may be extended to include adjacent newlines.
- If the range fully contains a paragraph belonging to a list, the paragraph's bullet is also updated with the matching text style.
Inserting text
- Inserting a newline character implicitly creates a new Paragraph at that index. The paragraph style of the new paragraph is copied from the paragraph at the current insertion index, including lists and bullets.
- Text styles for inserted text are determined automatically, generally preserving the styling of neighboring text. In most cases, the text style for the inserted text will match the text immediately before the insertion index.
- Some control characters and characters from the Unicode Basic Multilingual Plane Private Use Area (U+E000-U+F8FF) are stripped out of the inserted text.
Creating paragraph bullets
- The CreateParagraphBulletsRequest creates bullets for all of the paragraphs that overlap with the given range.
- The nesting level of each paragraph is determined by the number of leading tabs in front of each paragraph.
- The leading tabs are removed when creating the bullets, which may change the indexes of parts of the text.
- If you add paragraph bullets that match those of a list immediately before the target paragraph, the paragraph is joined to the list.
Deleting text
Deletions that result in an invalid document structure are not permitted. Some examples of invalid delete requests include:
- Deleting one code unit of a surrogate pair.
- Deleting the last newline character of a Body, Header, Footer, Footnote, TableCell, or TableOfContents.
- Deleting the start or end of a Table, TableOfContents, or Equation without deleting the entire element.
- Deleting the newline character before a Table, TableOfContents, or SectionBreak without deleting the element.
- Deleting individual rows or cells of a table. Deleting the content within a table cell is allowed.