Demote All Headings in a Google Doc Using Apps Script

by

(H1 → H2, H2 → H3, etc.)

When working with long Google Docs—course outlines, documentation, manuscripts, or AI-generated content—you often need to shift all heading levels down by one. For example:

  • H1 → H2
  • H2 → H3
  • H3 → H4
  • … and so on.

Doing this manually in a long document is tedious. Fortunately, Google Apps Script makes it possible to automate this task in seconds.

This post walks you through:

  • Why you must convert headings starting from H6 upward
  • The full Apps Script code
  • How the script works
  • How to install and run it in your Document

Why You Should Process Headings From H6 to H1

If you loop through headings from top to bottom (H1 → H6), you can accidentally overwrite existing headings.
Example:
If you convert H1 → H2 first, and later in the script you convert H2 → H3, the newly converted headings will also get changed—giving you incorrect results.

The fix is simple:
Start from the lowest level (H6) and move upward.

This ensures that each heading is changed exactly once.

The Complete Apps Script Code

This script demotes all headings by one level (H1→H2, H2→H3, … H5→H6).
Heading 6 becomes normal text — you can change this if you prefer.

function demoteHeadingsOneLevel() {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody();
  const paragraphs = body.getParagraphs();

  // Process from lowest to highest heading to avoid accidental overwriting
  const order = [
    DocumentApp.ParagraphHeading.HEADING6,
    DocumentApp.ParagraphHeading.HEADING5,
    DocumentApp.ParagraphHeading.HEADING4,
    DocumentApp.ParagraphHeading.HEADING3,
    DocumentApp.ParagraphHeading.HEADING2,
    DocumentApp.ParagraphHeading.HEADING1,
  ];

  order.forEach(function (headingType) {
    paragraphs.forEach(function (p) {
      if (p.getHeading() === headingType) {
        p.setHeading(demoteHeading_(headingType));
      }
    });
  });
}

/**
 * Returns the next level down for any heading.
 */
function demoteHeading_(heading) {
  const H = DocumentApp.ParagraphHeading;

  switch (heading) {
    case H.HEADING1:
      return H.HEADING2;
    case H.HEADING2:
      return H.HEADING3;
    case H.HEADING3:
      return H.HEADING4;
    case H.HEADING4:
      return H.HEADING5;
    case H.HEADING5:
      return H.HEADING6;
    case H.HEADING6:
      return H.NORMAL; // Change to H.HEADING6 if you want to keep H6 as H6
    default:
      return heading;
  }
}

How the Script Works

1. It retrieves all paragraphs in the Google Doc

Every element in a Google Doc is treated as a paragraph (including headings).

2. It defines the processing order

By starting from HEADING6 → HEADING1, the script ensures headings won’t get overwritten.

3. It loops through each paragraph

For every paragraph, it checks:

“Is this paragraph using the heading type I’m processing right now?”

If yes, it updates the heading to the next level.

4. It uses a small helper function

demoteHeading_() maps each heading level to the one below it.

How to Install the Script in Your Google Doc

Follow these quick steps:

1. Open your Google Doc

Any document will work.

2. Go to: Extensions → Apps Script

3. Delete the placeholder code and paste in the full script

4. Save the project

Give it any name you like—for example:
Heading Tools

5. Run the function: demoteHeadingsOneLevel()

The first time you run it, Google will ask for authorization.

6. Check your document

All headings will now be shifted down one level instantly.

Customization Options

You can easily modify the script depending on your needs.

Keep H6 as a heading

Change this line:

return H.NORMAL;

to:

return H.HEADING6;

Only demote certain heading types

Remove any you want to keep from the order list.

Promote headings instead (H3 → H2, etc.)

Reverse the logic—start from H1 downward and adjust the mapping.

Final Thoughts

This small but powerful script can save hours of manual formatting when dealing with long or AI-generated Docs. It’s especially useful for:

  • Instructional designers
  • Technical writers
  • Students
  • Authors
  • Anyone who imports text from multiple tools