0
# Linking and Media Extensions
1
2
Extensions for automatic linking, comprehensive emoji support, keyboard key formatting, and link processing enhancements for creating rich, interactive content.
3
4
## Capabilities
5
6
### Emoji Support
7
8
Comprehensive emoji support with multiple providers (Twemoji, EmojiOne, Gemoji) and customizable output formats including PNG, SVG, and sprites.
9
10
```python { .api }
11
def makeExtension(**kwargs):
12
"""
13
Create Emoji extension with multiple provider support.
14
15
Configuration:
16
- emoji_index: callable - Emoji index function (twemoji)
17
- emoji_generator: callable - Emoji HTML generator (to_svg)
18
- options: dict - Provider-specific options
19
20
Returns:
21
EmojiExtension instance
22
"""
23
24
class EmojiExtension(Extension):
25
"""Comprehensive emoji support extension."""
26
27
class EmojiPattern(InlineProcessor):
28
"""Emoji pattern processor."""
29
30
class EmojiAlertPostprocessor(Postprocessor):
31
"""Strict mode alert processor."""
32
33
# Provider index functions
34
def emojione(options, md):
35
"""EmojiOne emoji index provider."""
36
37
def gemoji(options, md):
38
"""GitHub Gemoji emoji index provider."""
39
40
def twemoji(options, md):
41
"""Twitter Twemoji emoji index provider."""
42
43
# Output format converters
44
def to_png(index, shortname, alias, uc, alt, options, **kwargs):
45
"""Convert emoji to PNG format."""
46
47
def to_svg(index, shortname, alias, uc, alt, options, **kwargs):
48
"""Convert emoji to SVG format."""
49
50
def to_png_sprite(index, shortname, alias, uc, alt, options, **kwargs):
51
"""Convert emoji to PNG sprite format."""
52
53
def to_svg_sprite(index, shortname, alias, uc, alt, options, **kwargs):
54
"""Convert emoji to SVG sprite format."""
55
56
def to_alt(index, shortname, alias, uc, alt, options, **kwargs):
57
"""Convert emoji to alt text format."""
58
59
def add_attributes(attrs={}):
60
"""Add custom attributes to emoji elements."""
61
62
# Backward compatibility alias (note: intentionally misspelled in source)
63
add_attriubtes = add_attributes
64
```
65
66
**Usage Example:**
67
68
```python
69
import markdown
70
from pymdownx import emoji
71
72
# Basic emoji support with Twemoji
73
md = markdown.Markdown(extensions=['pymdownx.emoji'])
74
75
# Custom configuration
76
md = markdown.Markdown(extensions=[
77
'pymdownx.emoji'
78
], extension_configs={
79
'pymdownx.emoji': {
80
'emoji_index': emoji.gemoji,
81
'emoji_generator': emoji.to_png,
82
'options': {
83
'attributes': {'align': 'absmiddle', 'height': '20px', 'width': '20px'},
84
'image_path': 'https://github.githubassets.com/images/icons/emoji/unicode/',
85
'non_standard_image_path': 'https://github.githubassets.com/images/icons/emoji/'
86
}
87
}
88
})
89
90
text = """
91
I love Python! :snake: :heart: :+1:
92
93
GitHub style: :octocat: :shipit:
94
95
Unicode: 🐍 ❤️ 👍
96
"""
97
html = md.convert(text)
98
```
99
100
### MagicLink (Automatic Linking)
101
102
Automatic linking for URLs, email addresses, and repository references with support for GitHub, GitLab, Bitbucket, and custom providers.
103
104
```python { .api }
105
def makeExtension(**kwargs):
106
"""
107
Create MagicLink extension for automatic linking.
108
109
Configuration:
110
- hide_protocol: bool - Hide protocol in displayed URLs (False)
111
- repo_url_shortener: bool - Shorten repository URLs (False)
112
- social_url_shortener: bool - Shorten social media URLs (False)
113
- provider: str - Repository provider ('github')
114
- user: str - Default repository user
115
- repo: str - Default repository name
116
117
Returns:
118
MagiclinkExtension instance
119
"""
120
121
class MagiclinkExtension(Extension):
122
"""Automatic linking extension."""
123
124
class MagiclinkPattern(InlineProcessor):
125
"""Link pattern processor."""
126
```
127
128
**Usage Example:**
129
130
```python
131
import markdown
132
133
md = markdown.Markdown(extensions=['pymdownx.magiclink'])
134
135
text = """
136
Visit https://www.example.com for more info.
137
138
Email me at user@example.com
139
140
Repository: facelessuser/pymdown-extensions
141
142
Issue: #123
143
Pull Request: !456
144
Commit: abc123def
145
"""
146
html = md.convert(text)
147
148
# With repository context
149
md = markdown.Markdown(extensions=[
150
'pymdownx.magiclink'
151
], extension_configs={
152
'pymdownx.magiclink': {
153
'provider': 'github',
154
'user': 'facelessuser',
155
'repo': 'pymdown-extensions'
156
}
157
})
158
```
159
160
### Keys (Keyboard Key Formatting)
161
162
Keyboard key styling and formatting with support for key combinations, modifiers, and custom key mappings.
163
164
```python { .api }
165
def makeExtension(**kwargs):
166
"""
167
Create Keys extension for keyboard key formatting.
168
169
Configuration:
170
- separator: str - Key combination separator ('+')
171
- strict: bool - Strict key validation (True)
172
- camel_case: bool - Use camelCase for key names (False)
173
174
Returns:
175
KeysExtension instance
176
"""
177
178
class KeysExtension(Extension):
179
"""Keyboard key formatting extension."""
180
181
class KeysPattern(InlineProcessor):
182
"""Key pattern processor."""
183
```
184
185
**Usage Example:**
186
187
```python
188
import markdown
189
190
md = markdown.Markdown(extensions=['pymdownx.keys'])
191
192
text = """
193
Press ++ctrl+alt+delete++ to restart.
194
195
Use ++cmd+c++ to copy on Mac.
196
197
Press ++f1++ for help.
198
199
Shortcut: ++ctrl+shift+p++
200
"""
201
html = md.convert(text)
202
```
203
204
### PathConverter (Path Processing)
205
206
Convert and normalize file paths in links with support for relative path resolution and cross-platform compatibility.
207
208
```python { .api }
209
def makeExtension(**kwargs):
210
"""
211
Create PathConverter extension for path processing.
212
213
Configuration:
214
- base_path: str - Base path for relative resolution
215
- relative_path: str - Relative path prefix
216
- absolute: bool - Convert to absolute paths (False)
217
- tags: str - HTML tags to process ('a img object embed')
218
219
Returns:
220
PathConverterExtension instance
221
"""
222
223
class PathConverterExtension(Extension):
224
"""Path conversion and normalization extension."""
225
226
class PathConverterTreeprocessor(Treeprocessor):
227
"""Path conversion processor."""
228
```
229
230
**Usage Example:**
231
232
```python
233
import markdown
234
235
md = markdown.Markdown(extensions=[
236
'pymdownx.pathconverter'
237
], extension_configs={
238
'pymdownx.pathconverter': {
239
'base_path': '/docs',
240
'relative_path': '../images/',
241
'absolute': True
242
}
243
})
244
245
text = """
246
247
248
[Document](../files/doc.pdf)
249
"""
250
html = md.convert(text)
251
```
252
253
## Emoji Configuration Patterns
254
255
### Provider Selection and Configuration
256
257
```python
258
from pymdownx import emoji
259
260
# Twemoji configuration
261
extension_configs = {
262
'pymdownx.emoji': {
263
'emoji_index': emoji.twemoji,
264
'emoji_generator': emoji.to_svg,
265
'options': {
266
'image_path': 'https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/',
267
'non_standard_image_path': 'https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/'
268
}
269
}
270
}
271
272
# GitHub Gemoji configuration
273
extension_configs = {
274
'pymdownx.emoji': {
275
'emoji_index': emoji.gemoji,
276
'emoji_generator': emoji.to_png,
277
'options': {
278
'image_path': 'https://github.githubassets.com/images/icons/emoji/unicode/',
279
'non_standard_image_path': 'https://github.githubassets.com/images/icons/emoji/'
280
}
281
}
282
}
283
284
# EmojiOne configuration
285
extension_configs = {
286
'pymdownx.emoji': {
287
'emoji_index': emoji.emojione,
288
'emoji_generator': emoji.to_svg,
289
'options': {
290
'image_path': 'https://cdn.jsdelivr.net/emojione/assets/svg/',
291
'non_standard_image_path': 'https://cdn.jsdelivr.net/emojione/assets/svg/'
292
}
293
}
294
}
295
```
296
297
### Custom Emoji Attributes
298
299
```python
300
from pymdownx.emoji import add_attributes
301
302
extension_configs = {
303
'pymdownx.emoji': {
304
'emoji_generator': add_attributes(
305
emoji.to_svg,
306
{'class': 'custom-emoji', 'height': '1em', 'width': '1em'}
307
)
308
}
309
}
310
```
311
312
## MagicLink Provider Configuration
313
314
### GitHub Integration
315
316
```python
317
extension_configs = {
318
'pymdownx.magiclink': {
319
'provider': 'github',
320
'user': 'username',
321
'repo': 'repository',
322
'repo_url_shortener': True,
323
'social_url_shortener': True
324
}
325
}
326
```
327
328
### GitLab Integration
329
330
```python
331
extension_configs = {
332
'pymdownx.magiclink': {
333
'provider': 'gitlab',
334
'user': 'username',
335
'repo': 'repository'
336
}
337
}
338
```
339
340
### Bitbucket Integration
341
342
```python
343
extension_configs = {
344
'pymdownx.magiclink': {
345
'provider': 'bitbucket',
346
'user': 'username',
347
'repo': 'repository'
348
}
349
}
350
```
351
352
## Advanced Linking Patterns
353
354
### Repository Reference Patterns
355
356
```python
357
# Issue references: #123
358
# Pull request references: !456
359
# Commit references: abc123def456
360
# Mention references: @username
361
# Repository references: user/repo
362
```
363
364
### Custom Key Mappings
365
366
```python
367
extension_configs = {
368
'pymdownx.keys': {
369
'separator': '-',
370
'strict': False,
371
'camel_case': True
372
}
373
}
374
```
375
376
## Constants and Databases
377
378
```python { .api }
379
# CDN URLs for emoji providers
380
EMOJIONE_SVG_CDN = "https://cdn.jsdelivr.net/emojione/assets/svg/"
381
TWEMOJI_SVG_CDN = "https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/"
382
TWEMOJI_PNG_CDN = "https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/72x72/"
383
GITHUB_CDN = "https://github.githubassets.com/images/icons/emoji/"
384
385
# Supported emoji indexes
386
SUPPORTED_INDEXES = ['emojione', 'twemoji', 'gemoji']
387
388
# Default exclusions for MagicLink providers
389
DEFAULT_EXCLUDES = {
390
'github': [...],
391
'gitlab': [...],
392
'bitbucket': [...]
393
}
394
```
395
396
## Types
397
398
```python { .api }
399
from typing import Callable, Dict, List, Optional, Any, Union
400
from markdown import Extension, InlineProcessor, Treeprocessor, Postprocessor
401
402
# Emoji-related types
403
EmojiIndex = Callable[[Dict, Any], Dict] # Emoji index provider function
404
EmojiGenerator = Callable[..., str] # Emoji HTML generator function
405
EmojiOptions = Dict[str, Any] # Emoji provider options
406
407
# Link-related types
408
LinkProcessor = Callable[[str], str] # Custom link processor
409
PathResolver = Callable[[str, str], str] # Path resolution function
410
ProviderConfig = Dict[str, Any] # Provider configuration
411
412
# Key-related types
413
KeySeparator = str # Key combination separator
414
KeyMap = Dict[str, str] # Custom key mappings
415
```