diff options
| -rw-r--r-- | .spell-dict | 1 | ||||
| -rw-r--r-- | docs/authors.md | 2 | ||||
| -rw-r--r-- | docs/cli.md | 2 | ||||
| -rw-r--r-- | docs/extensions/fenced_code_blocks.md | 4 | ||||
| -rw-r--r-- | docs/reference.md | 31 |
5 files changed, 20 insertions, 20 deletions
diff --git a/.spell-dict b/.spell-dict index 0ab92c6..5be5d6a 100644 --- a/.spell-dict +++ b/.spell-dict @@ -113,6 +113,7 @@ stdout Stelios Stienstra subclasses +SuperFences svn Swartz Szakmeister diff --git a/docs/authors.md b/docs/authors.md index 6b164fd..acf78b0 100644 --- a/docs/authors.md +++ b/docs/authors.md @@ -6,7 +6,7 @@ Primary Authors * __[Waylan Limberg](https://github.com/waylan)__ @waylan is the current maintainer of the code and has written much of the - current code base, included a complete refactor of the core for version 2.0. + current code base, including a complete refactor of the core for version 2.0. He started out by authoring many of the available extensions and later was asked to join Yuri, where he began fixing numerous bugs, adding documentation and making general improvements to the existing code base. diff --git a/docs/cli.md b/docs/cli.md index 1c4e40a..50e9ec2 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -55,7 +55,7 @@ path. * **Windows**: Assuming a default install of Python on Windows, your "Scripts" directory - is most likely something like `C:\\Python26\Scripts`. Verify the location + is most likely something like `C:\\Python37\Scripts`. Verify the location of your "Scripts" directory and add it to you system path. Calling `markdown_py` from the command line will call the wrapper batch diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md index 9095057..0a584f7 100644 --- a/docs/extensions/fenced_code_blocks.md +++ b/docs/extensions/fenced_code_blocks.md @@ -34,6 +34,10 @@ part of the list. Fenced Code Blocks are only supported at the document root level. Therefore, they cannot be nested inside lists or blockquotes. + If you need to nest fenced code blocks, you may want to try the + the third party extension [SuperFences] instead. + +[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ ### Language diff --git a/docs/reference.md b/docs/reference.md index 44fd174..8153ebe 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -25,7 +25,7 @@ instance of the `markdown.Markdown` class and pass multiple documents through it. If you do use a single instance though, make sure to call the `reset` method appropriately ([see below](#convert)). -### markdown.markdown(text [, **kwargs]) {: #markdown } +### markdown.markdown(text [, **kwargs]) {: #markdown data-toc-label='markdown.markdown' } The following options are available on the `markdown.markdown` function: @@ -34,24 +34,20 @@ __text__{: #text } : The source Unicode string. (required) !!! note "Important" - Python-Markdown expects **Unicode** as input (although - some simple ASCII strings *may* work) and returns output as Unicode. - Do not pass encoded strings to it! If your input is encoded, (e.g. as - UTF-8), it is your responsibility to decode it. For example: + Python-Markdown expects a **Unicode** string as input (some simple ASCII binary strings *may* work only by + coincidence) and returns output as a Unicode string. Do not pass binary strings to it! If your input is + encoded, (e.g. as UTF-8), it is your responsibility to decode it. For example: :::python - input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8") - text = input_file.read() + with open("some_file.txt", "r", encoding="utf-8") as input_file: + text = input_file.read() html = markdown.markdown(text) If you want to write the output to disk, you *must* encode it yourself: :::python - output_file = codecs.open("some_file.html", "w", - encoding="utf-8", - errors="xmlcharrefreplace" - ) - output_file.write(html) + with open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file: + output_file.write(html) __extensions__{: #extensions } @@ -181,7 +177,7 @@ __tab_length__{: #tab_length }: : Length of tabs in the source. Default: 4 -### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile } +### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile data-toc-label='markdown.markdownFromFile' } With a few exceptions, `markdown.markdownFromFile` accepts the same options as `markdown.markdown`. It does **not** accept a `text` (or Unicode) string. @@ -220,7 +216,7 @@ __encoding__{: #encoding } meet your specific needs, it is suggested that you write your own code to handle your encoding/decoding needs. -### markdown.Markdown([**kwargs]) {: #Markdown } +### markdown.Markdown([**kwargs]) {: #Markdown data-toc-label='markdown.Markdown' } The same options are available when initializing the `markdown.Markdown` class as on the [`markdown.markdown`](#markdown) function, except that the class does @@ -233,7 +229,7 @@ string must be passed to one of two instance methods. the thread they were created in. A single instance should not be accessed from multiple threads. -#### Markdown.convert(source) {: #convert } +#### Markdown.convert(source) {: #convert data-toc-label='Markdown.convert' } The `source` text must meet the same requirements as the [`text`](#text) argument of the [`markdown.markdown`](#markdown) function. @@ -248,8 +244,7 @@ html2 = md.convert(text2) ``` Depending on which options and/or extensions are being used, the parser may -need its state reset between each call to `convert`, otherwise performance -can degrade drastically: +need its state reset between each call to `convert`. ```python html1 = md.convert(text1) @@ -263,7 +258,7 @@ To make this easier, you can also chain calls to `reset` together: html3 = md.reset().convert(text3) ``` -#### Markdown.convertFile(**kwargs) {: #convertFile } +#### Markdown.convertFile(**kwargs) {: #convertFile data-toc-label='Markdown.convertFile' } The arguments of this method are identical to the arguments of the same name on the `markdown.markdownFromFile` function ([`input`](#input), |