How to Merge Paragraphs into H3 Headings in Google Docs Using Apps Script

by

Google Apps Script is a powerful tool that enables you to automate tasks and extend the functionality of Google Workspace apps, including Google Docs. In this blog post, we’ll explore a practical script that merges paragraphs into the preceding H3 headings and removes trailing colons from those headings. This can be especially useful for formatting documents where you want to combine a heading with its following paragraph into a single line.

Script Overview

The script below is designed to work within Google Docs. It iterates through the elements in the document, identifies H3 headings followed by paragraphs, merges the paragraph text into the heading, and then removes any trailing colon from the heading. Importantly, the script processes elements from the end of the document to the beginning, ensuring that changes to one element do not affect subsequent elements.

The Code

function mergeParagraphsIntoH3() {
  var doc = DocumentApp.getActiveDocument();
  var body = doc.getBody();
  var numElements = body.getNumChildren();

  // Loop from the end to the beginning
  for (var i = numElements - 1; i >= 0; i--) {
    var element = body.getChild(i);

    if (element.getType() == DocumentApp.ElementType.PARAGRAPH) {
      var paragraph = element.asParagraph();
      var prevElement = body.getChild(i - 1);

      // Check if the previous element is an H3 header
      if (prevElement.getType() == DocumentApp.ElementType.PARAGRAPH &&
          prevElement.asParagraph().getHeading() == DocumentApp.ParagraphHeading.HEADING3) {
        var h3Paragraph = prevElement.asParagraph();
        var h3Text = h3Paragraph.getText();

        // Get the current paragraph text
        var paragraphText = paragraph.getText().trim();

        // Append the paragraph text to the H3 element if it's not empty
        if (paragraphText.length > 0) {
          h3Paragraph.setText(h3Text + ' ' + paragraphText);
        }

        // Remove the current paragraph after merging
        body.removeChild(paragraph);

        // Remove the colon from the H3 text if it exists after merging
        h3Text = h3Paragraph.getText().replace(/:$/, '');
        h3Paragraph.setText(h3Text);
      }
    }
  }
}

How the Script Works

Let’s break down how this script functions:

  1. Accessing the Document Body:
    • The script starts by accessing the active document and its body, where all the elements (text, paragraphs, headings, etc.) are located.
  2. Looping in Reverse:
    • The script uses a for loop to iterate through all the elements in reverse order. This reverse iteration is crucial because it prevents changes made to one element from affecting the indexing of subsequent elements.
  3. Identifying Paragraphs and H3 Headings:
    • The script checks if the current element is a paragraph and then checks if the previous element is an H3 heading. If both conditions are met, it proceeds with the merging process.
  4. Merging Text:
    • The text from the paragraph is trimmed (to remove any unnecessary spaces) and then appended to the H3 heading. This merging is only done if the paragraph contains non-empty text.
  5. Removing the Paragraph:
    • Once the text has been merged, the script removes the paragraph from the document.
  6. Removing Trailing Colon:
    • Finally, the script checks if the H3 heading ends with a colon (:) and removes it. This ensures that the final H3 text is clean and formatted correctly.

Why Looping from the End Matters

When modifying a collection of elements in a list, especially when removing elements, starting from the end is a common practice. This is because when you remove an item from a list, all subsequent items are shifted forward, which can disrupt the indexing if you’re iterating from the beginning. By starting from the end, the script ensures that each element is handled correctly without affecting the remaining elements.

Practical Applications

This script can be particularly useful for automating document formatting tasks, such as when you’re preparing a document for publishing or creating consistent styles across multiple headings and paragraphs. It can save you time and reduce the likelihood of manual errors.

Conclusion

Google Apps Script offers a versatile way to automate and customize your Google Docs workflows. By understanding and leveraging scripts like this one, you can streamline your document management tasks and ensure consistent formatting. Whether you’re working on a large report, a book, or just a well-organized document, this script can help you achieve a polished final product.