How to Create and Apply Custom Styles in Word Documents Using OfficeCLI

OfficeCLI treats Word document styles as first-class objects in the OOXML /styles part, enabling you to create, modify, and apply custom styles using path-based commands with O(1) cached lookup performance.

The iOfficeAI/OfficeCLI repository provides a command-line interface for manipulating Office Open XML documents programmatically. When working with Word documents, understanding how to create and apply custom styles is essential for maintaining consistent formatting across large document automation workflows.

Understanding the OfficeCLI Style Architecture

OfficeCLI implements Word document styling as a semantic model mapped directly to the OOXML package structure. All styles reside in the /styles part of the document package and are accessible through the same path-based commands used for other document elements.

The WordHandler class maintains a _styleByIdCache dictionary for O(1) style lookup performance. When you first query a style, the FindStyleById method populates this cache by walking the <w:styles> collection【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/src/officecli/Handlers/WordHandler.cs#L56-L71】. Any mutation to the styles part triggers InvalidateStyleIndex to ensure the cache remains synchronized with the live document model.

For performance-critical operations, OfficeCLI employs a fast-path mutation strategy. The RawSet method detects /styles targets and uses a compiled XPath matcher /^/w:styles/w:style\[@w:styleId='([^']*)'\]$/ to replace individual <w:style> nodes without reparsing the entire part【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/src/officecli/Handlers/WordHandler.cs#L1894-L1916】.

Creating Custom Styles

To define a new style, use the add command targeting /styles with --type style and specify properties that map directly to the <w:style> element attributes.

Defining a Paragraph Style

The following example creates a custom paragraph style named "MyHeading" based on the built-in Heading1 style:

officecli add report.docx /styles --type style \
  --prop styleId=MyHeading \
  --prop type=paragraph \
  --prop name="My Heading" \
  --prop basedOn=Heading1 \
  --prop font=Georgia \
  --prop size=16pt \
  --prop color=#2A7AE2

Key properties include:

• styleId: Unique identifier for the style (required)
• type: Style type (paragraph, character, table, or numbering)
• basedOn: Parent style ID to inherit formatting from
• name: Display name shown in Word's style gallery
• font, size, color: Formatting attributes

The src/officecli/CommandBuilder.Add.cs file parses these --prop arguments and routes them to the OpenXML style builder before persisting to the document.

Applying Styles to Document Elements

Once created, apply styles by setting the style property on any document element. The style reference uses the styleId value defined during creation.

officecli add report.docx /body --type paragraph \
  --prop text="Executive Summary" \
  --prop style=MyHeading

This command creates a new paragraph in the document body and applies the custom "MyHeading" style. The style assignment modifies the paragraph's w:pPr/w:pStyle element in the underlying OOXML.

Modifying and Removing Styles

OfficeCLI supports both surgical updates to existing styles and complete removal.

Updating Existing Styles

Use the set command with an XPath targeting the specific style node to modify properties without recreating the entire style definition:

officecli set report.docx /styles/Style[@w:styleId='MyHeading'] \
  --prop color=#D9534F

This operation leverages the RawSet fast-path to update only the color property while preserving all other formatting attributes.

Deleting Styles

Remove style definitions entirely using the remove command:

officecli remove report.docx /styles/Style[@w:styleId='MyHeading']

Querying Available Styles

Inspect all styles present in a document using the view command:

officecli view report.docx /styles

This outputs the complete styles gallery, including both built-in Word styles and custom definitions you've added.

Summary

• OfficeCLI stores Word styles in the /styles OOXML part accessible through path-based commands
• The WordHandler maintains a _styleByIdCache for O(1) style lookups and uses InvalidateStyleIndex to keep the cache current
• Create styles with add /styles --type style and properties like styleId, basedOn, font, and color
• Apply styles to elements using the style property in add or set commands
• Update styles efficiently via RawSet compiled XPath matching without full part reparsing
• Reference implementation details in src/officecli/Handlers/WordHandler.cs lines 56-71 and 1894-1916

Frequently Asked Questions

What file format does OfficeCLI use for Word documents?

OfficeCLI operates on the Office Open XML (OOXML) format used by modern Word documents (.docx). The tool manipulates the underlying XML parts directly, including the /styles part that contains all style definitions as <w:style> elements.

How does OfficeCLI handle style lookup performance?

The WordHandler class implements a caching strategy using _styleByIdCache to achieve O(1) lookups after the initial style discovery. The FindStyleById method populates this cache on first access by iterating through the <w:styles> collection. When styles are modified, InvalidateStyleIndex clears the cache to ensure subsequent operations read the updated definitions.

Can I base custom styles on built-in Word styles?

Yes. Use the basedOn property when creating a style to inherit formatting from any existing style, including built-in Word styles like Heading1, Normal, or Title. This creates a style hierarchy where your custom style inherits default formatting that you can override with specific properties like font or color.

Is it possible to apply styles to elements other than paragraphs?

Absolutely. The type property when creating styles supports paragraph, character, table, and numbering values. When applying styles, you can reference character styles for runs of text, table styles for table elements, or paragraph styles for block-level elements depending on the target element's capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}