Automating Google Docs: Adjusting Heading Levels with Apps Script

Google Docs provides a powerful platform for creating and organizing documents, but managing heading levels across a document can sometimes become tedious. If you’ve ever wanted to automatically adjust headings to one level lower throughout a document, you’re in luck! The updateHeadingLevels script simplifies this process, ensuring all headings are updated correctly while preserving formatting.

This blog post will walk you through how this script works and why it’s a handy tool for document automation.


Why Automate Heading Adjustments?

Manually adjusting heading levels in a long document is error-prone and time-consuming. Common use cases for automating this include:

  • Standardizing heading structures in collaborative documents.
  • Preparing documents for formatting or publishing requirements.
  • Automating repetitive editing tasks for efficiency.

The updateHeadingLevels function is designed to:

  1. Downgrade all headings by one level.
  2. Convert Heading 4 to bold normal text.
  3. Process headings sequentially, starting from Heading 4 to prevent conflicts.

The Script in Action

Below is the complete script:

function updateHeadingLevels() {
const doc = DocumentApp.getActiveDocument();
const body = doc.getBody();

// Array of heading types in the correct order for processing
const headings = [
DocumentApp.ParagraphHeading.HEADING4,
DocumentApp.ParagraphHeading.HEADING3,
DocumentApp.ParagraphHeading.HEADING2,
DocumentApp.ParagraphHeading.HEADING1
];

// Iterate through each heading level starting from the smallest
for (let i = 0; i < headings.length; i++) {
const headingType = headings[i];
const paragraphs = body.getParagraphs();

for (let j = 0; j < paragraphs.length; j++) {
const paragraph = paragraphs[j];

if (paragraph.getHeading() === headingType) {
const newHeading = getNextHeadingAsHeading(headingType);
if (newHeading) {
if (headingType === DocumentApp.ParagraphHeading.HEADING4 && newHeading === DocumentApp.ParagraphHeading.NORMAL) {
// Convert Heading 4 to Normal but keep it bold
paragraph.setHeading(DocumentApp.ParagraphHeading.NORMAL);
paragraph.setBold(true);
} else {
paragraph.setHeading(newHeading);
}
}
}
}
}
}

// Helper function to determine the next heading level as a heading
function getNextHeadingAsHeading(currentHeading) {
switch (currentHeading) {
case DocumentApp.ParagraphHeading.HEADING1:
return DocumentApp.ParagraphHeading.HEADING2;
case DocumentApp.ParagraphHeading.HEADING2:
return DocumentApp.ParagraphHeading.HEADING3;
case DocumentApp.ParagraphHeading.HEADING3:
return DocumentApp.ParagraphHeading.HEADING4;
case DocumentApp.ParagraphHeading.HEADING4:
return DocumentApp.ParagraphHeading.NORMAL;
default:
return null;
}
}

How It Works

  1. Identify Headings: The script loops through all paragraphs in the document, checking their heading type (e.g., HEADING1, HEADING2).
  2. Process Smallest First: By processing Heading 4 first, it ensures no conflicts arise when adjusting higher-level headings.
  3. Downgrade Levels: Each heading is adjusted to the next lower level using the helper function getNextHeadingAsHeading().
  4. Special Case for Heading 4: When converting Heading 4, the script ensures it becomes bold normal text instead of losing emphasis.

Example Use Case

Suppose you have the following heading structure in your document:

  • Heading 1: Introduction
  • Heading 2: Background
  • Heading 3: Details
  • Heading 4: Example

After running this script:

  • Heading 1 becomes Heading 2.
  • Heading 2 becomes Heading 3.
  • Heading 3 becomes Heading 4.
  • Heading 4 becomes Normal Bold Text.

Running the Script

  1. Open Google Apps Script:
    • In your Google Doc, go to Extensions > Apps Script.
  2. Paste the Script:
    • Copy and paste the script into the editor.
  3. Run the Script:
    • Select the updateHeadingLevels function and click the play ▶️ button.
  4. Authorize:
    • If running for the first time, grant necessary permissions.

Benefits of This Script

  • Efficiency: Automates an otherwise manual and tedious process.
  • Accuracy: Ensures consistent heading structure across the document.
  • Flexibility: Easily adjustable to include or exclude specific heading types.

Conclusion

The updateHeadingLevels script is a powerful tool for automating heading adjustments in Google Docs. Whether you’re managing a collaborative document or preparing content for publication, this script saves time and effort while maintaining a professional structure.