How to Automate Word with VBA Macros, Office Add-ins and Python

The Tutoring Club's template kit from Tutorial 1 made documents consistent. But coordinators still repeat the same chores: cleaning text pasted from emails, styling every tip box, updating fields before a PDF goes out, making sixty certificates. Each chore is small. Together they eat hours, and people make mistakes when they are bored.

In this tutorial you will decide which chores are worth automating, compare the tools Word gives you (from no-code AutoCorrect to VBA, Office add-ins and Python), record a macro and turn it into readable code, and learn how to share it without teaching anyone to switch off macro security.

Decide what's worth automating

Automation costs time up front: building, testing, explaining and fixing it later. It pays off when a task scores high on at least two of three things:

• Frequency: how often someone does it (per week, per term).
• Time: how many minutes it takes each time.
• Error risk: how bad a mistake is (a typo in a child's name on a certificate is worse than an extra space).

A quick estimate: times per term × minutes each gives the time you could save. Double it if mistakes are costly. If building the automation would take longer than that, wait or pick a simpler tool.

Notice that the first two rows need no code at all. Always try the simplest tool first: Quick Parts and AutoText for repeated content, AutoCorrect (File› then Options› then Proofing› then AutoCorrect Options) for repeated typos, and mail merge for one document per row of a list.

Compare your options

Each tool runs in a different place and needs different skills. Pick by where the people who will use it work.

Record a macro

A macro is a small program saved under a name. The quickest way to make one is to let Word watch you. You can record from View› then Macros› then Record Macro, or turn on the Developer tab (File› then Options› then Customize Ribbon, tick Developer) and use its Code group.

1. Prepare. Open a copy of the messy handout. Decide the exact steps before you start; every click is recorded.
2. Name it. Click Record Macro and type a name with no spaces, such as CleanHandout.
3. Choose where it lives. In Store macro in, All Documents (Normal.dotm) makes it available in every document on your computer. Choosing the open document keeps it inside that file.
4. Optional shortcut. Click Button to add it to the Quick Access Toolbar, or Keyboard to give it a key combination that isn't already used.
5. Do the steps. Click OK, press Ctrl+H, type two spaces in Find what and one in Replace with, click Replace All, close the dialog.
6. Stop. Click View› then Macros› then Stop Recording (or the same button on the Developer tab).
7. Run it. Press Alt+F8, pick CleanHandout and click Run.

Read and improve the code in the VBA editor

Press Alt+F11 (or Developer› then Code› then Visual Basic) to open the Visual Basic Editor. In the Project pane on the left, open Normal > Modules > NewMacros. Your recording looks something like this:

Sub CleanHandout()
'
' CleanHandout Macro
'
    Selection.Find.ClearFormatting
    Selection.Find.Replacement.ClearFormatting
    With Selection.Find
        .Text = "  "
        .Replacement.Text = " "
        .Forward = True
        .Wrap = wdFindContinue
        .Format = False
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = False
        .MatchSoundsLike = False
        .MatchAllWordForms = False
    End With
    Selection.Find.Execute Replace:=wdReplaceAll
End Sub

Word recorded every setting in the Replace dialog, used the Selection (the cursor), and replaced only pairs of spaces, so three spaces become two. Here is the same idea rewritten so a teammate can read it, plus empty-paragraph cleanup using the wildcards from the Advanced find and replace tutorial:

Option Explicit

' Cleans pasted text in a handout. Run it on a copy first.
Sub CleanHandout()
    ' Two or more spaces become one space
    ReplaceAllWild " {2,}", " "
    ' Repeated paragraph marks become one: no empty paragraphs
    ReplaceAllWild "^13{2,}", "^p"
End Sub

' Wildcard Replace All in the main text of the active document
Private Sub ReplaceAllWild(findText As String, _
                           replaceText As String)
    Dim rng As Range
    ' The whole main text, not the selection
    Set rng = ActiveDocument.Content
    With rng.Find
        .ClearFormatting
        .Replacement.ClearFormatting
        .Text = findText
        .Replacement.Text = replaceText
        .MatchWildcards = True
        .Execute Replace:=wdReplaceAll
    End With
End Sub

What changed and why:

• Option Explicit at the top makes VBA refuse to run if you misspell a variable name, instead of quietly creating a new empty one. Turn it on for every new module with Tools› then Options in the editor and tick Require Variable Declaration.
• Comments start with an apostrophe. Write why as well as what.
• A Range instead of the Selection. ActiveDocument.Content is the whole main text, so the macro does the same thing wherever the cursor is, and the screen doesn't jump around.
• A small helper (ReplaceAllWild) is written once and called twice, so adding a third cleanup is one line.

Now a macro you couldn't record at all, because it makes a decision for each paragraph. It needs a paragraph style named Tip Box in the document (from the kit template):

Option Explicit

' Applies Tip Box to every paragraph that starts with "Tip:"
Sub StyleTips()
    Dim para As Paragraph
    Dim count As Long

    For Each para In ActiveDocument.Paragraphs
        If LCase(Left(para.Range.Text, 4)) = "tip:" Then
            para.Range.Style = ActiveDocument.Styles("Tip Box")
            ' Remove hand formatting, keep the style
            para.Range.Font.Reset
            count = count + 1
        End If
    Next para

    MsgBox count & " tip paragraphs now use Tip Box."
End Sub

Save, share and trust macros safely

An ordinary .docx can't hold macros. If you save a document with a macro as .docx, Word warns that the VB project can't be saved in a macro-free document, and the macro is removed. Choose where the code should live:

For a team, the tidy choice is a separate TC Tools.dotm that holds only the club's macros, while the kit templates stay macro-free .dotx files. Each coordinator loads it with Developer› then Templates› then Document Template: under Global templates and add-ins, click Add. The macros then appear in Alt+F8 in every document, but the documents themselves stay .docx.

Macro security. Macros can do anything Word can, including deleting files, so Word is careful about them. The settings live in File› then Options› then Trust Center› then Trust Center Settings› then Macro Settings, and the safe default is to disable macros with a notification. Files that came from the internet, including email attachments, carry a Mark of the Web, and Microsoft 365 blocks macros in them by default with a red Security Risk bar.

Office add-ins: automation that works everywhere

An Office add-in is a small web app that runs inside Word, usually as a pane on the right. It is written in HTML and JavaScript using the Word JavaScript API, and the same add-in works in Word for Windows, Mac and the web. You find installed ones under Home› then Add-ins or Developer› then Add-ins› then Word Add-ins, depending on your version.

The code talks to the document through objects much like VBA's, but it works in batches: you queue up requests, then context.sync() sends them to Word. This is the tip-styling idea as an add-in would do it:

// Word JavaScript API, inside an add-in:
// style every paragraph that starts with "Tip:"
await Word.run(async (context) => {
  const paras = context.document.body.paragraphs;
  paras.load("items/text");
  await context.sync();
  for (const p of paras.items) {
    if (p.text.toLowerCase().startsWith("tip:")) {
      p.style = "Tip Box";
    }
  }
  await context.sync();
});

Building one is a web development project: you need a manifest file, a place to host the web files, and a way to deploy it. Developers can sideload an add-in to test it; for a team, a Microsoft 365 admin usually deploys it from the admin center, and public add-ins are listed in Microsoft's add-in store. For the Tutoring Club, an add-in only makes sense if many volunteers use Word for the web and a volunteer with web skills will maintain it. Start from the Word add-ins documentation linked in Sources.

Batch work outside Word: python-docx and Power Automate

python-docx is a free Python library that reads and writes .docx files directly, without opening Word. It is ideal when you have many files to create or check. This script makes one certificate per student from a base document that has a [Name] line:

# pip install python-docx
from docx import Document

names = ["Ana Lopez", "Min-jun Park", "Sam Lee"]

for name in names:
    # A .docx saved from the kit template
    doc = Document("Certificate base.docx")
    for para in doc.paragraphs:
        if "[Name]" in para.text:
            para.text = para.text.replace("[Name]", name)
    doc.save(f"Certificate - {name}.docx")

And this one lists how many headings each handout in a folder has, a quick way to find handouts that were formatted by hand instead of with styles:

from pathlib import Path
from docx import Document

for path in sorted(Path("Handouts").glob("*.docx")):
    doc = Document(str(path))
    heads = [p.text for p in doc.paragraphs
             if p.style.name.startswith("Heading")]
    print(path.name, "-", len(heads), "headings:", heads[:3])

• Start from a .docx, not the .dotx. python-docx opens documents, so save a .docx from the kit template and use it as the base; it keeps all the styles.
• Setting para.text keeps the paragraph style but replaces the bold or colored parts inside it with plain text. Format the placeholder line with a paragraph style, not by hand.
• It isn't Word. It can't update fields or a table of contents, work out page numbers or save PDFs. Open the results in Word for those steps, or run a VBA macro over them.
• Work on copies in their own folder, so a script mistake can't overwrite the originals.

Power Automate is Microsoft's cloud workflow tool. If your organization has it, a flow can, for example, take a sign-up form response, fill a Word template's content controls with the answers, convert the result to PDF and save it to SharePoint. Some of the Word actions need a premium license, and what you can use depends on your Microsoft 365 plan, so check with whoever manages your account before you plan around it.

Common mistakes

Practice