Paragraph formatting¶

WordprocessingML supports a variety of paragraph formatting attributes to control layout characteristics such as justification, indentation, line spacing, space before and after, and widow/orphan control.

Alignment (justification)¶

In Word, each paragraph has an alignment attribute that specifies how to justify the lines of the paragraph when the paragraph is laid out on the page. Common values are left, right, centered, and justified.

Protocol¶

Getting and setting paragraph alignment:

>>> paragraph = body.add_paragraph()
>>> paragraph.alignment
None
>>> paragraph.alignment = WD_ALIGN_PARAGRAPH.RIGHT
>>> paragraph.alignment
RIGHT (2)
>>> paragraph.alignment = None
>>> paragraph.alignment
None

XML Semantics¶

If the <w:jc> element is not present on a paragraph, the alignment value for that paragraph is inherited from its style hierarchy. If the element is present, its value overrides any inherited value. From the API, a value of None on the Paragraph.alignment property corresponds to no <w:jc> element being present. If None is assigned to Paragraph.alignment, the <w:jc> element is removed.

Paragraph spacing¶

Spacing between subsequent paragraphs is controlled by the paragraph spacing attributes. Spacing can be applied either before the paragraph, after it, or both. The concept is similar to that of padding or margin in CSS. WordprocessingML supports paragraph spacing specified as either a length value or as a multiple of the line height; however only a length value is supported via the Word UI. Inter-paragraph spacing “overlaps”, such that the rendered spacing between two paragraphs is the maximum of the space after the first paragraph and the space before the second.

Protocol¶

Getting and setting paragraph spacing:

>>> paragraph_format = document.styles['Normal'].paragraph_format
>>> paragraph_format.space_before
None
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.space_before.pt
12.0

XML Semantics¶

Paragraph spacing is specified using the w:pPr/w:spacing element, which also controls line spacing. Spacing is specified in twips.
If the w:spacing element is not present, paragraph spacing is inherited from the style hierarchy.
If not present in the style hierarchy, the paragraph will have no spacing.
If the w:spacing element is present but the specific attribute (e.g. w:before) is not, its value is inherited.

Specimen XML¶

12 pt space before, 0 after:

<w:pPr>
  <w:spacing w:before="240" w:after="0"/>
</w:pPr>

Line spacing¶

Line spacing can be specified either as a specific length or as a multiple of the line height (font size). Line spacing is specified by the combination of values in w:spacing/@w:line and w:spacing/@w:lineRule. The ParagraphFormat.line_spacing property determines which method to use based on whether the assigned value is an instance of Length.

Protocol¶

Getting and setting line spacing:

>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(None, None)

>>> paragraph_format.line_spacing = Pt(18)
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(228600, WD_LINE_SPACING.EXACTLY (4))

>>> paragraph_format.line_spacing = 1
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(152400, WD_LINE_SPACING.SINGLE (0))

>>> paragraph_format.line_spacing = 0.9
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(137160, WD_LINE_SPACING.MULTIPLE (5))

XML Semantics¶

Line spacing is specified by the combination of the values in w:spacing/@w:line and w:spacing/@w:lineRule.
w:spacing/@w:line is specified in twips. If @w:lineRule is ‘auto’ (or missing), @w:line is interpreted as 240ths of a line. For all other values of @w:lineRule, the value of @w:line is interpreted as a specific length in twips.
If the w:spacing element is not present, line spacing is inherited.
If @w:line is not present, line spacing is inherited.
If not present, @w:lineRule defaults to ‘auto’.
If not present in the style hierarchy, line spacing defaults to single spaced.
The ‘atLeast’ value for @w:lineRule indicates the line spacing will be @w:line twips or single spaced, whichever is greater.

Specimen XML¶

14 points:

<w:pPr>
  <w:spacing w:line="280"/>
</w:pPr>

double-spaced:

<w:pPr>
  <w:spacing w:line="480" w:lineRule="exact"/>
</w:pPr>

Indentation¶

Paragraph indentation is specified using the w:pPr/w:ind element. Left, right, first line, and hanging indent can be specified. Indentation can be specified as a length or in hundredths of a character width. Only length is supported by python-docx. Both first line indent and hanging indent are specified using the ParagraphFormat.first_line_indent property. Assigning a positive value produces an indented first line. A negative value produces a hanging indent.

Protocol¶

Getting and setting indentation:

>>> paragraph_format.left_indent
None
>>> paragraph_format.right_indent
None
>>> paragraph_format.first_line_indent
None

>>> paragraph_format.left_indent = Pt(36)
>>> paragraph_format.left_indent.pt
36.0

>>> paragraph_format.right_indent = Inches(0.25)
>>> paragraph_format.right_indent.pt
18.0

>>> paragraph_format.first_line_indent = Pt(-18)
>>> paragraph_format.first_line_indent.pt
-18.0

XML Semantics¶

Indentation is specified by w:ind/@w:start, w:ind/@w:end, w:ind/@w:firstLine, and w:ind/@w:hanging.
w:firstLine and w:hanging are mutually exclusive, if both are specified, w:firstLine is ignored.
All four attributes are specified in twips.
w:start controls left indent for a left-to-right paragraph or right indent for a right-to-left paragraph. w:end controls the other side. If mirrorIndents is specified, w:start controls the inside margin and w:end the outside. Negative values are permitted and cause the text to move past the text margin.
If w:ind is not present, indentation is inherited.
Any omitted attributes are inherited.
If not present in the style hierarchy, indentation values default to zero.

Specimen XML¶

1 inch left, 0.5 inch (additional) first line, 0.5 inch right:

<w:pPr>
  <w:ind w:start="1440" w:end="720" w:firstLine="720"/>
</w:pPr>

0.5 inch left, 0.5 inch hanging indent:

<w:pPr>
  <w:ind w:start="720" w:hanging="720"/>
</w:pPr>

Page placement¶

There are a handful of page placement properties that control such things as keeping the lines of a paragraph together on the same page, keeing a paragraph (such as a heading) on the same page as the subsequent paragraph, and placing the paragraph at the top of a new page. Each of these are tri-state boolean properties where None indicates “inherit”.

Protocol¶

Getting and setting indentation:

>>> paragraph_format.keep_with_next
None
>>> paragraph_format.keep_together
None
>>> paragraph_format.page_break_before
None
>>> paragraph_format.widow_control
None

>>> paragraph_format.keep_with_next = True
>>> paragraph_format.keep_with_next
True

>>> paragraph_format.keep_together = False
>>> paragraph_format.keep_together
False

>>> paragraph_format.page_break_before = True
>>> paragraph_format.widow_control = None

XML Semantics¶

All four elements have “On/Off” semantics.
If not present, their value is inherited.
If not present in the style hierarchy, values default to False.

Specimen XML¶

keep with next, keep together, no page break before, and widow/orphan control:

<w:pPr>
  <w:keepNext/>
  <w:keepLines/>
  <w:pageBreakBefore w:val="0"/>
  <w:widowControl/>
</w:pPr>

Enumerations¶

Specimen XML¶

A paragraph with inherited alignment:

<w:p>
  <w:r>
    <w:t>Inherited paragraph alignment.</w:t>
  </w:r>
</w:p>

A right-aligned paragraph:

<w:p>
  <w:pPr>
    <w:jc w:val="right"/>
  </w:pPr>
  <w:r>
    <w:t>Right-aligned paragraph.</w:t>
  </w:r>
</w:p>

Schema excerpt¶

<xsd:complexType name="CT_PPr">  <!-- denormalized -->
  <xsd:sequence>
    <xsd:element name="pStyle"              type="CT_String"           minOccurs="0"/>
    <xsd:element name="keepNext"            type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="keepLines"           type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="pageBreakBefore"     type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="framePr"             type="CT_FramePr"          minOccurs="0"/>
    <xsd:element name="widowControl"        type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="numPr"               type="CT_NumPr"            minOccurs="0"/>
    <xsd:element name="suppressLineNumbers" type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="pBdr"                type="CT_PBdr"             minOccurs="0"/>
    <xsd:element name="shd"                 type="CT_Shd"              minOccurs="0"/>
    <xsd:element name="tabs"                type="CT_Tabs"             minOccurs="0"/>
    <xsd:element name="suppressAutoHyphens" type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="kinsoku"             type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="wordWrap"            type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="overflowPunct"       type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="topLinePunct"        type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="autoSpaceDE"         type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="autoSpaceDN"         type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="bidi"                type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="adjustRightInd"      type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="snapToGrid"          type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="spacing"             type="CT_Spacing"          minOccurs="0"/>
    <xsd:element name="ind"                 type="CT_Ind"              minOccurs="0"/>
    <xsd:element name="contextualSpacing"   type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="mirrorIndents"       type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="suppressOverlap"     type="CT_OnOff"            minOccurs="0"/>
    <xsd:element name="jc"                  type="CT_Jc"               minOccurs="0"/>
    <xsd:element name="textDirection"       type="CT_TextDirection"    minOccurs="0"/>
    <xsd:element name="textAlignment"       type="CT_TextAlignment"    minOccurs="0"/>
    <xsd:element name="textboxTightWrap"    type="CT_TextboxTightWrap" minOccurs="0"/>
    <xsd:element name="outlineLvl"          type="CT_DecimalNumber"    minOccurs="0"/>
    <xsd:element name="divId"               type="CT_DecimalNumber"    minOccurs="0"/>
    <xsd:element name="cnfStyle"            type="CT_Cnf"              minOccurs="0"/>
    <xsd:element name="rPr"                 type="CT_ParaRPr"          minOccurs="0"/>
    <xsd:element name="sectPr"              type="CT_SectPr"           minOccurs="0"/>
    <xsd:element name="pPrChange"           type="CT_PPrChange"        minOccurs="0"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CT_FramePr">
  <xsd:attribute name="dropCap"    type="ST_DropCap"/>
  <xsd:attribute name="lines"      type="ST_DecimalNumber"/>
  <xsd:attribute name="w"          type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="h"          type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="vSpace"     type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="hSpace"     type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="wrap"       type="ST_Wrap"/>
  <xsd:attribute name="hAnchor"    type="ST_HAnchor"/>
  <xsd:attribute name="vAnchor"    type="ST_VAnchor"/>
  <xsd:attribute name="x"          type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="xAlign"     type="s:ST_XAlign"/>
  <xsd:attribute name="y"          type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="yAlign"     type="s:ST_YAlign"/>
  <xsd:attribute name="hRule"      type="ST_HeightRule"/>
  <xsd:attribute name="anchorLock" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_Ind">
  <xsd:attribute name="start"          type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="startChars"     type="ST_DecimalNumber"/>
  <xsd:attribute name="end"            type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="endChars"       type="ST_DecimalNumber"/>
  <xsd:attribute name="left"           type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="leftChars"      type="ST_DecimalNumber"/>
  <xsd:attribute name="right"          type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="rightChars"     type="ST_DecimalNumber"/>
  <xsd:attribute name="hanging"        type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="hangingChars"   type="ST_DecimalNumber"/>
  <xsd:attribute name="firstLine"      type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="firstLineChars" type="ST_DecimalNumber"/>
</xsd:complexType>

<xsd:complexType name="CT_Jc">
  <xsd:attribute name="val" type="ST_Jc" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_OnOff">
  <xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_Spacing">
  <xsd:attribute name="before"            type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="beforeLines"       type="ST_DecimalNumber"/>
  <xsd:attribute name="beforeAutospacing" type="s:ST_OnOff"/>
  <xsd:attribute name="after"             type="s:ST_TwipsMeasure"/>
  <xsd:attribute name="afterLines"        type="ST_DecimalNumber"/>
  <xsd:attribute name="afterAutospacing"  type="s:ST_OnOff"/>
  <xsd:attribute name="line"              type="ST_SignedTwipsMeasure"/>
  <xsd:attribute name="lineRule"          type="ST_LineSpacingRule"/>
</xsd:complexType>

<xsd:complexType name="CT_String">
  <xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_Tabs">
  <xsd:sequence>
    <xsd:element name="tab" type="CT_TabStop" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

<!-- simple types -->

<xsd:simpleType name="ST_Jc">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="start"/>
    <xsd:enumeration value="center"/>
    <xsd:enumeration value="end"/>
    <xsd:enumeration value="both"/>
    <xsd:enumeration value="mediumKashida"/>
    <xsd:enumeration value="distribute"/>
    <xsd:enumeration value="numTab"/>
    <xsd:enumeration value="highKashida"/>
    <xsd:enumeration value="lowKashida"/>
    <xsd:enumeration value="thaiDistribute"/>
    <xsd:enumeration value="left"/>
    <xsd:enumeration value="right"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_LineSpacingRule">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="auto"/>  <!-- default -->
    <xsd:enumeration value="exact"/>
    <xsd:enumeration value="atLeast"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff">
  <xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff1">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="on"/>
    <xsd:enumeration value="off"/>
  </xsd:restriction>
</xsd:simpleType>

Paragraph formatting¶

Alignment (justification)¶

Protocol¶

XML Semantics¶

Paragraph spacing¶

Protocol¶

XML Semantics¶

Specimen XML¶

Line spacing¶

Protocol¶

XML Semantics¶

Specimen XML¶

Indentation¶

Protocol¶

XML Semantics¶

Specimen XML¶

Page placement¶

Protocol¶

XML Semantics¶

Specimen XML¶

Enumerations¶

Specimen XML¶

Schema excerpt¶

Table of Contents

Previous topic

Next topic

Useful Links