.DOCX File Format – Paragraphs and runs

Office Open XML Document

A paragraph, w:p, holds runs: stretches of text with the same formatting. Text never sits directly in a paragraph; it is always in a w:t inside a w:r.

An example

<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
    <w:jc w:val="center"/>
  </w:pPr>
  <w:r>
    <w:t xml:space="preserve">A plain and </w:t>
  </w:r>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:color w:val="C00000"/>
    </w:rPr>
    <w:t>bold red</w:t>
  </w:r>
  <w:r>
    <w:t xml:space="preserve"> heading</w:t>
  </w:r>
</w:p>
One paragraph of three runs. xml:space="preserve" keeps the spaces at the ends of the text.

Paragraph properties: w:pPr

w:pPr is the first child of the paragraph. Its children have a fixed order in the schema; the most used are:

ElementMeaning
w:pStyleThe paragraph’s style, by style ID.
w:keepNext, w:keepLinesKeep with the next paragraph; keep the paragraph’s lines together.
w:pageBreakBeforeStart a new page.
w:framePrText frame properties.
w:widowControlPrevent widows and orphans.
w:numPrList membership: w:ilvl and w:numId.
w:suppressLineNumbersDo not number these lines.
w:pBdrBorders: w:top, w:left, w:bottom, w:right, w:between, w:bar.
w:shdShading.
w:tabsCustom tab stops: w:tab with w:val and w:pos.
w:spacingw:before, w:after (twips), w:line, w:lineRule (auto, in 240ths of a line, exact or atLeast, in twips).
w:indIndents: w:left, w:right (w:start, w:end in Strict), w:hanging, w:firstLine.
w:contextualSpacingIgnore spacing between paragraphs of the same style.
w:mirrorIndentsSwap indents on facing pages.
w:jcAlignment: left, center, right, both and others (start, end in Strict).
w:outlineLvlOutline level, 0 to 8 for headings; 9 for body text.
w:rPrThe formatting of the paragraph mark, and w:ins or w:del when the paragraph mark is tracked.
w:sectPrThis paragraph ends a section.
w:pPrChangeThe previous paragraph properties, under tracked changes.

Inside a paragraph

Besides runs, a paragraph can contain:

ElementMeaning
w:hyperlinkA hyperlink around runs.
w:fldSimpleA simple field around its result runs.
w:ins, w:del, w:moveFrom, w:moveToRuns under tracked changes.
w:sdtA content control around runs.
w:smartTagRuns recognised as a smart tag.
w:bookmarkStart, w:bookmarkEndBookmarks.
w:commentRangeStart, w:commentRangeEndComment anchors.
m:oMath, m:oMathParaEquations.
w:proofErrSpelling or grammar marks.

Run properties: w:rPr

w:rPr is the first child of the run. Elements present set a property on the run, and they override what the styles give.

ElementMeaning
w:rStyleA character style, by style ID.
w:rFontsFonts: w:ascii, w:hAnsi, w:eastAsia, w:cs, and theme fonts.
w:b, w:bCsBold, for ordinary text and complex-script text.
w:i, w:iCsItalic.
w:caps, w:smallCapsDisplay capitals, or small capitals.
w:strike, w:dstrikeStruck through, once or twice.
w:outline, w:shadow, w:emboss, w:imprintText effects.
w:vanishHidden text.
w:colorText colour: w:val (RGB hex or auto), optionally a theme colour.
w:spacingCharacter spacing in twips.
w:positionRaised or lowered, in half-points.
w:sz, w:szCsFont size in half-points: 24 is 12 point.
w:highlightHighlight: a named colour.
w:uUnderline: w:val single, double, dotted, none and others.
w:shd, w:bdrShading and border of the run.
w:vertAlignsuperscript, subscript or baseline.
w:langThe language of the text, for proofing.
w:rtl, w:csRight-to-left; complex script.
w:rPrChangeThe previous run properties, under tracked changes.

On/off properties such as w:b follow one rule: the element alone means on, and w:val can be 1, true or on for on, and 0, false or off for off. An element set to off is different from an absent one: it turns off what a style would turn on. See style resolution.

Run content

ElementMeaning
w:tText. xml:space="preserve" keeps leading and trailing spaces.
w:delText, w:instrText, w:delInstrTextDeleted text, field instructions and deleted field instructions.
w:tab, w:ptabA tab; an absolute position tab.
w:brA break: w:type textWrapping (the default), page or column.
w:crA carriage return, as a line break.
w:noBreakHyphen, w:softHyphenA non-breaking and an optional hyphen.
w:symA symbol by font and character code: w:font, w:char.
w:fldCharThe start, separator or end of a complex field.
w:drawing, w:pict, w:objectPictures and shapes, in DrawingML or VML, and OLE objects.
w:footnoteReference, w:endnoteReferenceA note reference by ID.
w:commentReferenceWhere a comment is anchored.
w:rubyPhonetic guide text: w:rt above w:rubyBase.
w:lastRenderedPageBreakA note of where a page ended when the file was last laid out. It is not a break.

A run’s elements are read in order: one run can hold text, tabs and line breaks. Word splits text across several runs wherever formatting, spell-checking or editing history differ, so the same word can appear in pieces, and a reader must join them. The w:rsidR and w:rsidRPr attributes record the editing session that last changed a run; they do not affect the text.