| 1 |
title: SmartyPants Extension |
| 2 |
|
| 3 |
SmartyPants |
| 4 |
=========== |
| 5 |
|
| 6 |
Summary |
| 7 |
------- |
| 8 |
|
| 9 |
The SmartyPants extension converts ASCII dashes, quotes and ellipses to |
| 10 |
their HTML entity equivalents. |
| 11 |
|
| 12 |
ASCII symbol | Replacements | HTML Entities | Substitution Keys |
| 13 |
------------ | --------------- | ------------------- | ---------------------------------------- |
| 14 |
`'` | ‘ ’ | `‘` `’` | `'left-single-quote'`, `'right-single-quote'` |
| 15 |
`"` | “ ” | `“` `”` | `'left-double-quote'`, `'right-double-quote'` |
| 16 |
`<< >>` | « » | `«` `»` | `'left-angle-quote'`, `'right-angle-quote'` |
| 17 |
`...` | … | `…` | `'ellipsis'` |
| 18 |
`--` | – | `–` | `'ndash'` |
| 19 |
`---` | — | `—` | `'mdash'` |
| 20 |
|
| 21 |
Using the configuration option 'substitutions' you can overwrite the |
| 22 |
default substitutions. Just pass a dict mapping (a subset of) the |
| 23 |
keys to the substitution strings. |
| 24 |
|
| 25 |
For example, one might use the following configuration to get correct quotes for |
| 26 |
the German language: |
| 27 |
|
| 28 |
```python |
| 29 |
extension_configs = { |
| 30 |
'smarty': { |
| 31 |
'substitutions': { |
| 32 |
'left-single-quote': '‚', # sb is not a typo! |
| 33 |
'right-single-quote': '‘', |
| 34 |
'left-double-quote': '„', |
| 35 |
'right-double-quote': '“' |
| 36 |
} |
| 37 |
} |
| 38 |
} |
| 39 |
``` |
| 40 |
|
| 41 |
!!! note |
| 42 |
This extension re-implements the Python [SmartyPants] |
| 43 |
library by integrating it into the markdown parser. |
| 44 |
While this does not provide any additional features, |
| 45 |
it does offer a few advantages. Notably, it will not |
| 46 |
try to work on highlighted code blocks (using the |
| 47 |
[CodeHilite] Extension) like the third party library |
| 48 |
has been known to do. |
| 49 |
|
| 50 |
[SmartyPants]: https://pythonhosted.org/smartypants/ |
| 51 |
[CodeHilite]: code_hilite.md |
| 52 |
|
| 53 |
Usage |
| 54 |
----- |
| 55 |
|
| 56 |
See [Extensions](index.md) for general extension usage. Use `smarty` as the |
| 57 |
name of the extension. |
| 58 |
|
| 59 |
See the [Library Reference](../reference.md#extensions) for information about |
| 60 |
configuring extensions. |
| 61 |
|
| 62 |
The following options are provided to configure the output: |
| 63 |
|
| 64 |
Option | Default value | Description |
| 65 |
------ | ------------- | ----------- |
| 66 |
`smart_dashes` | `True` | whether to convert dashes |
| 67 |
`smart_quotes` | `True` | whether to convert straight quotes |
| 68 |
`smart_angled_quotes` | `False` | whether to convert angled quotes |
| 69 |
`smart_ellipses` | `True` | whether to convert ellipses |
| 70 |
`substitutions` | `{}` | overwrite default substitutions |
| 71 |
|
| 72 |
A trivial example: |
| 73 |
|
| 74 |
```python |
| 75 |
markdown.markdown(some_text, extensions=['smarty']) |
| 76 |
``` |
| 77 |
|
| 78 |
Further reading |
| 79 |
--------------- |
| 80 |
|
| 81 |
SmartyPants extension is based on the original SmartyPants implementation |
| 82 |
by John Gruber. Please read its [documentation][1] for details. |
| 83 |
|
| 84 |
[1]: https://daringfireball.net/projects/smartypants/ |