1title: Library Reference 2 3# Using Markdown as a Python Library 4 5First and foremost, Python-Markdown is intended to be a python library module 6used by various projects to convert Markdown syntax into HTML. 7 8## The Basics 9 10To use markdown as a module: 11 12```python 13import markdown 14html = markdown.markdown(your_text_string) 15``` 16 17## The Details 18 19Python-Markdown provides two public functions ([`markdown.markdown`](#markdown) 20and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the 21public class [`markdown.Markdown`](#Markdown). If you're processing one 22document at a time, these functions will serve your needs. However, if you need 23to process multiple documents, it may be advantageous to create a single 24instance of the `markdown.Markdown` class and pass multiple documents through 25it. If you do use a single instance though, make sure to call the `reset` 26method appropriately ([see below](#convert)). 27 28### markdown.markdown(text [, **kwargs]) {: #markdown data-toc-label='markdown.markdown' } 29 30The following options are available on the `markdown.markdown` function: 31 32__text__{: #text } 33 34: The source Unicode string. (required) 35 36 !!! note "Important" 37 Python-Markdown expects a **Unicode** string as input (some simple ASCII binary strings *may* work only by 38 coincidence) and returns output as a Unicode string. Do not pass binary strings to it! If your input is 39 encoded, (e.g. as UTF-8), it is your responsibility to decode it. For example: 40 41 :::python 42 with open("some_file.txt", "r", encoding="utf-8") as input_file: 43 text = input_file.read() 44 html = markdown.markdown(text) 45 46 If you want to write the output to disk, you *must* encode it yourself: 47 48 :::python 49 with open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file: 50 output_file.write(html) 51 52__extensions__{: #extensions } 53 54: A list of extensions. 55 56 Python-Markdown provides an [API](extensions/api.md) for third parties to 57 write extensions to the parser adding their own additions or changes to the 58 syntax. A few commonly used extensions are shipped with the markdown 59 library. See the [extension documentation](extensions/index.md) for a 60 list of available extensions. 61 62 The list of extensions may contain instances of extensions and/or strings 63 of extension names. 64 65 :::python 66 extensions=[MyExtClass(), 'myext', 'path.to.my.ext:MyExtClass'] 67 68 !!! note 69 The preferred method is to pass in an instance of an extension. Strings 70 should only be used when it is impossible to import the Extension Class 71 directly (from the command line or in a template). 72 73 When passing in extension instances, each class instance must be a subclass 74 of `markdown.extensions.Extension` and any configuration options should be 75 defined when initiating the class instance rather than using the 76 [`extension_configs`](#extension_configs) keyword. For example: 77 78 :::python 79 from markdown.extensions import Extension 80 class MyExtClass(Extension): 81 # define your extension here... 82 83 markdown.markdown(text, extensions=[MyExtClass(option='value')]) 84 85 If an extension name is provided as a string, the string must either be the 86 registered entry point of any installed extension or the importable path 87 using Python's dot notation. 88 89 See the documentation specific to an extension for the string name assigned 90 to an extension as an entry point. Simply include the defined name as 91 a string in the list of extensions. For example, if an extension has the 92 name `myext` assigned to it and the extension is properly installed, then 93 do the following: 94 95 :::python 96 markdown.markdown(text, extensions=['myext']) 97 98 If an extension does not have a registered entry point, Python's dot 99 notation may be used instead. The extension must be installed as a 100 Python module on your PYTHONPATH. Generally, a class should be specified in 101 the name. The class must be at the end of the name and be separated by a 102 colon from the module. 103 104 Therefore, if you were to import the class like this: 105 106 :::python 107 from path.to.module import MyExtClass 108 109 Then load the extension as follows: 110 111 :::python 112 markdown.markdown(text, extensions=['path.to.module:MyExtClass']) 113 114 If only one extension is defined within a module and the module includes a 115 `makeExtension` function which returns an instance of the extension, then 116 the class name is not necessary. For example, in that case one could do 117 `extensions=['path.to.module']`. Check the documentation for a specific 118 extension to determine if it supports this feature. 119 120 When loading an extension by name (as a string), you can only pass in 121 configuration settings to the extension by using the 122 [`extension_configs`](#extension_configs) keyword. 123 124 !!! seealso "See Also" 125 See the documentation of the [Extension API](extensions/api.md) for 126 assistance in creating extensions. 127 128__extension_configs__{: #extension_configs } 129 130: A dictionary of configuration settings for extensions. 131 132 Any configuration settings will only be passed to extensions loaded by name 133 (as a string). When loading extensions as class instances, pass the 134 configuration settings directly to the class when initializing it. 135 136 !!! Note 137 The preferred method is to pass in an instance of an extension, which 138 does not require use of the `extension_configs` keyword at all. 139 See the [extensions](#extensions) keyword for details. 140 141 The dictionary of configuration settings must be in the following format: 142 143 :::python 144 extension_configs = { 145 'extension_name_1': { 146 'option_1': 'value_1', 147 'option_2': 'value_2' 148 }, 149 'extension_name_2': { 150 'option_1': 'value_1' 151 } 152 } 153 154 When specifying the extension name, be sure to use the exact same 155 string as is used in the [extensions](#extensions) keyword to load the 156 extension. Otherwise, the configuration settings will not be applied to 157 the extension. In other words, you cannot use the entry point in on 158 place and Python dot notation in the other. While both may be valid for 159 a given extension, they will not be recognized as being the same 160 extension by Markdown. 161 162 See the documentation specific to the extension you are using for help in 163 specifying configuration settings for that extension. 164 165__output_format__{: #output_format }: 166 167: Format of output. 168 169 Supported formats are: 170 171 * `"xhtml"`: Outputs XHTML style tags. **Default**. 172 * `"html5"`: Outputs HTML style tags. 173 174 The values can be in either lowercase or uppercase. 175 176__tab_length__{: #tab_length }: 177 178: Length of tabs in the source. Default: 4 179 180### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile data-toc-label='markdown.markdownFromFile' } 181 182With a few exceptions, `markdown.markdownFromFile` accepts the same options as 183`markdown.markdown`. It does **not** accept a `text` (or Unicode) string. 184Instead, it accepts the following required options: 185 186__input__{: #input } (required) 187 188: The source text file. 189 190 `input` may be set to one of three options: 191 192 * a string which contains a path to a readable file on the file system, 193 * a readable file-like object, 194 * or `None` (default) which will read from `stdin`. 195 196__output__{: #output } 197 198: The target which output is written to. 199 200 `output` may be set to one of three options: 201 202 * a string which contains a path to a writable file on the file system, 203 * a writable file-like object, 204 * or `None` (default) which will write to `stdout`. 205 206__encoding__{: #encoding } 207 208: The encoding of the source text file. 209 210 Defaults to `"utf-8"`. The same encoding will always be used for input and output. 211 The `xmlcharrefreplace` error handler is used when encoding the output. 212 213 !!! Note 214 This is the only place that decoding and encoding of Unicode 215 takes place in Python-Markdown. If this rather naive solution does not 216 meet your specific needs, it is suggested that you write your own code 217 to handle your encoding/decoding needs. 218 219### markdown.Markdown([**kwargs]) {: #Markdown data-toc-label='markdown.Markdown' } 220 221The same options are available when initializing the `markdown.Markdown` class 222as on the [`markdown.markdown`](#markdown) function, except that the class does 223**not** accept a source text string on initialization. Rather, the source text 224string must be passed to one of two instance methods. 225 226!!! warning 227 228 Instances of the `markdown.Markdown` class are only thread safe within 229 the thread they were created in. A single instance should not be accessed 230 from multiple threads. 231 232#### Markdown.convert(source) {: #convert data-toc-label='Markdown.convert' } 233 234The `source` text must meet the same requirements as the [`text`](#text) 235argument of the [`markdown.markdown`](#markdown) function. 236 237You should also use this method if you want to process multiple strings 238without creating a new instance of the class for each string. 239 240```python 241md = markdown.Markdown() 242html1 = md.convert(text1) 243html2 = md.convert(text2) 244``` 245 246Depending on which options and/or extensions are being used, the parser may 247need its state reset between each call to `convert`. 248 249```python 250html1 = md.convert(text1) 251md.reset() 252html2 = md.convert(text2) 253``` 254 255To make this easier, you can also chain calls to `reset` together: 256 257```python 258html3 = md.reset().convert(text3) 259``` 260 261#### Markdown.convertFile(**kwargs) {: #convertFile data-toc-label='Markdown.convertFile' } 262 263The arguments of this method are identical to the arguments of the same 264name on the `markdown.markdownFromFile` function ([`input`](#input), 265[`output`](#output), and [`encoding`](#encoding)). As with the 266[`convert`](#convert) method, this method should be used to 267process multiple files without creating a new instance of the class for 268each document. State may need to be `reset` between each call to 269`convertFile` as is the case with `convert`. 270