Google Docs

Overview

This skill provides instructions for working with Google Docs operations. It covers creating documents, reading document content, and modifying document contents and structure through the batchUpdate API. Note that certain operations (deleting documents, renaming documents, managing Drive folders) require Google Drive authentication.

Restrictions

The Google Docs API (google-docs auth) can perform:

• Create documents
• Read document content and structure
• Modify document contents using documents.batchUpdate:
  • Insert / delete / move text
  • Insert / delete paragraphs, headings, lists
  • Insert / modify tables
  • Insert / position images
  • Apply styles & formatting (bold, italics, fonts, colors, paragraph styles)
  • Work with links, bookmarks, footers, headers, footnotes

The Google Docs API CANNOT perform (requires Google Drive authentication):

• Delete documents
• Rename/update document title
• Create documents in specific Drive folders
• Move documents between folders
• Change sharing/permissions
• List documents
• Copy documents
• Export documents to other formats

Important: The Google Docs API controls document contents (text, formatting, tables, etc.), but the Google Drive API owns file metadata including the document's title/name.

For operations requiring Google Drive auth, use google_drive which provides complete instructions for file management operations.

• Document indices start at 1 (not 0). Index 1 is the beginning of the document body.
• Requests in batchUpdate are executed sequentially. When inserting content, subsequent indices shift accordingly.
• When updating styles, always specify the fields parameter to indicate which style properties to update.
• Content operations use the Docs API, but file operations (delete, rename, move, share, list, create in folders) require the Drive API. For these operations, use google_drive.

Operations

Create Document

Create a new Google Doc using the documents.create API endpoint:

const createResponse = await fetch("https://docs.googleapis.com/v1/documents", {
  method: "POST",
  headers: {
    Authorization: "Bearer GOOGLE_DOCS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Document Title",
  }),
});

const document = await createResponse.json();
// document.documentId contains the new document's ID

Key parameters:

• title: The title of the document (optional, defaults to "Untitled document")

Response includes:

• documentId: The ID of the newly created document
• title: The document title
• body: The document body structure
• documentStyle: Default document styling

Read Document

Retrieve a document's content and structure using the documents.get API endpoint:

const readResponse = await fetch(
  `https://docs.googleapis.com/v1/documents/${documentId}`,
  {
    headers: {
      Authorization: "Bearer GOOGLE_DOCS_TOKEN",
    },
  }
);

const document = await readResponse.json();

Response structure:

• documentId: The document ID
• title: Document title
• body: Document content structure with paragraphs, tables, images, etc.
• headers: Map of header IDs to header content
• footers: Map of footer IDs to footer content
• inlineObjects: Images and other inline objects
• lists: Numbered and bulleted lists
• namedRanges: Bookmarks and named ranges

Modify Document Content

Update document content and structure using the documents.batchUpdate API endpoint. This endpoint accepts an array of requests that are executed in order:

const updateResponse = await fetch(
  `https://docs.googleapis.com/v1/documents/${documentId}:batchUpdate`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer GOOGLE_DOCS_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      requests: [
        // Array of update requests (see examples below)
      ],
    }),
  }
);

const result = await updateResponse.json();

Common batchUpdate operations:

Insert Text

{
  requests: [
    {
      insertText: {
        location: {
          index: 1, // Position to insert (1 = start of document)
        },
        text: "Hello, World!\n",
      },
    },
  ];
}

Delete Text

{
  requests: [
    {
      deleteContentRange: {
        range: {
          startIndex: 1,
          endIndex: 10, // Delete characters 1-9
        },
      },
    },
  ];
}

Apply Text Formatting

{
  requests: [
    {
      updateTextStyle: {
        range: {
          startIndex: 1,
          endIndex: 10,
        },
        textStyle: {
          bold: true,
          italic: true,
          fontSize: {
            magnitude: 14,
            unit: "PT",
          },
          foregroundColor: {
            color: {
              rgbColor: {
                red: 1.0,
                green: 0.0,
                blue: 0.0,
              },
            },
          },
        },
        fields: "bold,italic,fontSize,foregroundColor",
      },
    },
  ];
}

Insert Paragraph

{
  requests: [
    {
      insertText: {
        location: { index: 1 },
        text: "New paragraph\n",
      },
    },
    {
      updateParagraphStyle: {
        range: {
          startIndex: 1,
          endIndex: 15,
        },
        paragraphStyle: {
          namedStyleType: "HEADING_1", // or NORMAL_TEXT, HEADING_2, etc.
        },
        fields: "namedStyleType",
      },
    },
  ];
}

Insert Table

{
  requests: [
    {
      insertTable: {
        rows: 3,
        columns: 3,
        location: {
          index: 1,
        },
      },
    },
  ];
}

Insert Image

{
  requests: [
    {
      insertInlineImage: {
        location: {
          index: 1,
        },
        uri: "https://example.com/image.jpg",
        objectSize: {
          height: {
            magnitude: 200,
            unit: "PT",
          },
          width: {
            magnitude: 300,
            unit: "PT",
          },
        },
      },
    },
  ];
}

Workflows

Creating a Document with Initial Content

To create a document with content, first create the document, then use batchUpdate to add content:

// Step 1: Create the document
const createResponse = await fetch("https://docs.googleapis.com/v1/documents", {
  method: "POST",
  headers: {
    Authorization: "Bearer GOOGLE_DOCS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "My New Document",
  }),
});

const document = await createResponse.json();
const documentId = document.documentId;

// Step 2: Add content using batchUpdate
const updateResponse = await fetch(
  `https://docs.googleapis.com/v1/documents/${documentId}:batchUpdate`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer GOOGLE_DOCS_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      requests: [
        {
          insertText: {
            location: { index: 1 },
            text: "Document Title\n\nThis is the first paragraph.\n",
          },
        },
        {
          updateParagraphStyle: {
            range: { startIndex: 1, endIndex: 15 },
            paragraphStyle: { namedStyleType: "HEADING_1" },
            fields: "namedStyleType",
          },
        },
        {
          updateTextStyle: {
            range: { startIndex: 17, endIndex: 47 },
            textStyle: { bold: true },
            fields: "bold",
          },
        },
      ],
    }),
  }
);

Reading and Understanding Document Structure

When reading a document, the content is organized hierarchically:

const response = await fetch(
  `https://docs.googleapis.com/v1/documents/${documentId}`,
  {
    headers: {
      Authorization: "Bearer GOOGLE_DOCS_TOKEN",
    },
  }
);

const document = await response.json();

// Access document content
const body = document.body;

// Iterate through content
for (const element of body.content) {
  if (element.paragraph) {
    // This is a paragraph
    const paragraph = element.paragraph;
    for (const paragraphElement of paragraph.elements) {
      if (paragraphElement.textRun) {
        console.log(paragraphElement.textRun.content);
      }
    }
  } else if (element.table) {
    // This is a table
    const table = element.table;
    console.log(`Table with ${table.rows} rows`);
  }
}

Complex Document Updates

For complex updates, chain multiple requests in a single batchUpdate call:

const updateResponse = await fetch(
  `https://docs.googleapis.com/v1/documents/${documentId}:batchUpdate`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer GOOGLE_DOCS_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      requests: [
        // Insert heading
        {
          insertText: {
            location: { index: 1 },
            text: "Project Report\n",
          },
        },
        {
          updateParagraphStyle: {
            range: { startIndex: 1, endIndex: 16 },
            paragraphStyle: { namedStyleType: "HEADING_1" },
            fields: "namedStyleType",
          },
        },
        // Insert subheading
        {
          insertText: {
            location: { index: 16 },
            text: "Executive Summary\n",
          },
        },
        {
          updateParagraphStyle: {
            range: { startIndex: 16, endIndex: 34 },
            paragraphStyle: { namedStyleType: "HEADING_2" },
            fields: "namedStyleType",
          },
        },
        // Insert body text
        {
          insertText: {
            location: { index: 34 },
            text: "This report summarizes our findings...\n",
          },
        },
        // Insert table
        {
          insertTable: {
            rows: 3,
            columns: 2,
            location: { index: 75 },
          },
        },
      ],
    }),
  }
);