0
# Rich Text Formatting
1

2
Advanced text formatting capabilities for creating rich content within templates. DocxTpl provides classes for styled text, hyperlinks, and complex paragraph formatting that preserve Word document styling while enabling programmatic content generation.
3

4
## Capabilities
5

6
### RichText Class
7

8
Class for generating formatted rich text within existing paragraphs. Allows complex formatting combinations including fonts, colors, styles, and hyperlinks.
9

10
```python { .api }
11
class RichText:
12
    def __init__(self, text=None, **text_prop):
13
        """
14
        Initialize RichText with optional initial text and formatting properties.
15
        
16
        Parameters:
17
        - text: Initial text content
18
        - **text_prop: Initial formatting properties (style, color, bold, etc.)
19
        """
20
```
21

22
### Rich Text Content Addition
23

24
Add formatted text segments to build complex rich text elements.
25

26
```python { .api }
27
def add(self, text, style=None, color=None, highlight=None, size=None, 
28
        subscript=None, superscript=None, bold=False, italic=False, 
29
        underline=False, strike=False, font=None, url_id=None, 
30
        rtl=False, lang=None):
31
    """
32
    Add formatted text segment to the rich text element.
33
    
34
    Parameters:
35
    - text: Text content to add
36
    - style: Word style name to apply
37
    - color: Text color (RGB hex string like 'FF0000' or color name)
38
    - highlight: Highlight color for text background
39
    - size: Font size in points
40
    - subscript: Enable subscript formatting (bool)
41
    - superscript: Enable superscript formatting (bool)
42
    - bold: Enable bold formatting (bool)
43
    - italic: Enable italic formatting (bool)
44
    - underline: Enable underline formatting (bool)
45
    - strike: Enable strikethrough formatting (bool)
46
    - font: Font family name
47
    - url_id: URL ID for hyperlink (use DocxTemplate.build_url_id())
48
    - rtl: Right-to-left text direction (bool)
49
    - lang: Language code for text
50
    """
51
```
52

53
### RichText String Methods
54

55
Methods for converting rich text to XML representation for template insertion.
56

57
```python { .api }
58
def __str__(self) -> str:
59
    """Return XML representation of rich text."""
60

61
def __unicode__(self) -> str:
62
    """Return Unicode XML representation of rich text."""
63

64
def __html__(self) -> str:
65
    """Return HTML-like representation of rich text."""
66
```
67

68
### RichTextParagraph Class
69

70
Class for generating rich text paragraphs outside existing paragraphs. Creates standalone paragraph elements with rich formatting.
71

72
```python { .api }
73
class RichTextParagraph:
74
    def __init__(self, text=None, **text_prop):
75
        """
76
        Initialize RichTextParagraph with optional initial text and properties.
77
        
78
        Parameters:
79
        - text: Initial text content
80
        - **text_prop: Initial formatting properties
81
        """
82
```
83

84
### Rich Paragraph Content Addition
85

86
Add paragraph content with specific paragraph-level styling.
87

88
```python { .api }
89
def add(self, text, parastyle=None):
90
    """
91
    Add paragraph with formatting.
92
    
93
    Parameters:
94
    - text: Paragraph text content
95
    - parastyle: Word paragraph style name to apply
96
    """
97
```
98

99
### RichTextParagraph String Methods
100

101
Methods for converting rich text paragraphs to XML representation.
102

103
```python { .api }
104
def __str__(self) -> str:
105
    """Return XML representation of rich text paragraph."""
106

107
def __unicode__(self) -> str:
108
    """Return Unicode XML representation of rich text paragraph."""
109

110
def __html__(self) -> str:
111
    """Return HTML-like representation of rich text paragraph."""
112
```
113

114
### Type Aliases
115

116
Convenient aliases for rich text classes.
117

118
```python { .api }
119
R = RichText         # Alias for RichText class
120
RP = RichTextParagraph  # Alias for RichTextParagraph class
121
```
122

123
## Usage Examples
124

125
### Basic Rich Text Formatting
126

127
```python
128
from docxtpl import DocxTemplate, RichText
129

130
doc = DocxTemplate("template.docx")
131

132
# Create rich text with multiple formats
133
rt = RichText()
134
rt.add("Hello ", bold=True, color="FF0000")
135
rt.add("World", italic=True, color="0000FF", underline=True)
136
rt.add("!", size=16, font="Arial")
137

138
context = {
139
    'greeting': rt
140
}
141

142
doc.render(context)
143
doc.save("formatted_output.docx")
144
```
145

146
### Advanced Text Formatting
147

148
```python
149
from docxtpl import DocxTemplate, RichText, R
150

151
doc = DocxTemplate("report_template.docx")
152

153
# Using alias and advanced formatting
154
title = R("IMPORTANT NOTICE", bold=True, size=14, color="FF0000", highlight="FFFF00")
155

156
# Build formatted content with hyperlinks
157
url_id = doc.build_url_id("https://example.com")
158
content = R()
159
content.add("Visit our website ", color="000000")
160
content.add("here", color="0000FF", underline=True, url_id=url_id)
161
content.add(" for more information.", color="000000")
162

163
context = {
164
    'notice_title': title,
165
    'website_link': content
166
}
167

168
doc.render(context)
169
doc.save("notice.docx")
170
```
171

172
### Rich Text Paragraphs
173

174
```python
175
from docxtpl import DocxTemplate, RichTextParagraph, RP
176

177
doc = DocxTemplate("document_template.docx")
178

179
# Create formatted paragraphs
180
header = RP("Executive Summary", parastyle="Heading 1")
181
intro = RP("This document provides an overview of our quarterly results.", parastyle="Normal")
182

183
# Multi-format paragraph
184
conclusion = RP()
185
conclusion.add("In conclusion, ", bold=False)
186
conclusion.add("performance exceeded expectations", bold=True, color="008000")
187
conclusion.add(" in all key metrics.", bold=False)
188

189
context = {
190
    'header': header,
191
    'introduction': intro,
192
    'conclusion': conclusion
193
}
194

195
doc.render(context)
196
doc.save("executive_summary.docx")
197
```
198

199
### Scientific Text with Subscripts and Superscripts
200

201
```python
202
from docxtpl import DocxTemplate, RichText
203

204
doc = DocxTemplate("scientific_template.docx")
205

206
# Chemical formula
207
formula = RichText()
208
formula.add("H", color="000000")
209
formula.add("2", subscript=True, color="000000")
210
formula.add("SO", color="000000")
211
formula.add("4", subscript=True, color="000000")
212

213
# Mathematical expression
214
math_expr = RichText()
215
math_expr.add("E = mc", color="000000")
216
math_expr.add("2", superscript=True, color="000000")
217

218
context = {
219
    'chemical_formula': formula,
220
    'einstein_equation': math_expr
221
}
222

223
doc.render(context)
224
doc.save("scientific_document.docx")
225
```
226

227
### Multi-language Support
228

229
```python
230
from docxtpl import DocxTemplate, RichText
231

232
doc = DocxTemplate("multilingual_template.docx")
233

234
# Right-to-left text support
235
arabic_text = RichText("مرحبا بالعالم", rtl=True, lang="ar-SA", font="Arial Unicode MS")
236

237
# Mixed language content
238
mixed = RichText()
239
mixed.add("English text ", lang="en-US")
240
mixed.add("中文文本", lang="zh-CN", font="SimSun")
241
mixed.add(" français", lang="fr-FR")
242

243
context = {
244
    'arabic_greeting': arabic_text,
245
    'multilingual_text': mixed
246
}
247

248
doc.render(context)
249
doc.save("multilingual_document.docx")
250
```