Debian Codegraph @

docs/extensions/smarty.md

raw
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 `<< >>` | &laquo; &raquo; | `&laquo;` `&raquo;` | `'left-angle-quote'`, `'right-angle-quote'`
17 `...` | &hellip; | `&hellip;` | `'ellipsis'`
18 `--` | &ndash; | `&ndash;` | `'ndash'`
19 `---` | &mdash; | `&mdash;` | `'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': '&sbquo;', # sb is not a typo!
33 'right-single-quote': '&lsquo;',
34 'left-double-quote': '&bdquo;',
35 'right-double-quote': '&ldquo;'
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/