diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/extensions/header_id.txt | 9 | ||||
| -rw-r--r-- | docs/extensions/toc.txt | 92 | ||||
| -rw-r--r-- | docs/release-2.6.txt | 43 |
3 files changed, 110 insertions, 34 deletions
diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt index 2881c50..42e640e 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.txt @@ -15,6 +15,13 @@ elements (`h1`-`h6`) in the resulting HTML document. This extension is included in the standard Markdown library. +!!! warning + This extension is **Pending Deprecation**. The [Table of Contents][toc] + Extension should be used instead, which offers most the features of this + extension and more. + +[toc]: toc.html + Syntax ------ @@ -55,7 +62,7 @@ The following options are provided to configure the output: >>> text = ''' ... #Some Header ... ## Next Level''' - >>> from markdown.extensions.headerid import HeaderIdExtension + >>> from markdown.extensions.headerid import HeaderIdExtension >>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)]) >>> print html <h3 id="some_header">Some Header</h3> diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index 56a8ee0..c6a99bf 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -18,6 +18,20 @@ This extension is included in the standard Markdown library. Syntax ------ +By default, all headers will automatically have unique `id` attributes +generated based upon the text of the header. Note this example, in which all +three headers would have the same `id`: + + #Header + #Header + #Header + +Results in: + + <h1 id="header">Header</h1> + <h1 id="header_1">Header</h1> + <h1 id="header_2">Header</h1> + Place a marker in the document where you would like the Table of Contents to appear. Then, a nested list of all the headers in the document will replace the marker. The marker defaults to `[TOC]` so the following document: @@ -41,6 +55,14 @@ would generate the following output: <h1 id="header-1">Header 1</h1> <h1 id="header-2">Header 2</h1> +Regardless of whether a `marker` is found in the document (or disabled), the Table of +Contents is available as an attribute (`toc`) on the Markdown class. This allows +one to insert the Table of Contents elsewhere in their page template. For example: + + >>> md = markdown.Markdown(extensions=['markdown.extensions.toc']) + >>> html = md.convert(text) + >>> page = render_some_template(context={'body': html, 'toc': md.toc}) + Usage ----- @@ -53,37 +75,57 @@ configuring extensions. The following options are provided to configure the output: * **`marker`**: - Text to find and replace with the Table of Contents. Defaults - to `[TOC]`. + Text to find and replace with the Table of Contents. Defaults to `[TOC]`. + + Set to an empty string to disable searching for a marker, which may save some time, + especially on long documents. - Regardless of whether a `marker` is found in the document, the Table of Contents is - also available as an attribute (`toc`) of the Markdown class. This allows one to insert - the Table of Contents elsewhere in their page template. For example: +* **`title`**: + Title to insert in the Table of Contents' `<div>`. Defaults to `None`. - >>> text = ''' - # Header 1 +* **`anchorlink`**: + Set to `True` to cause all headers to link to themselves. Default is `False`. - ## Header 2 - ''' - >>> md = markdown.Markdown(extensions=['markdown.extensions.toc']) - >>> html = md.convert(text) - >>> render_some_template(context={'body': html, 'toc': md.toc}) +* **`permalink`**: + Set to `True` or a string to generate permanent links at the end of each header. + Useful with Sphinx stylesheets. + + When set to `True` the paragraph symbol (¶ -- `¶`) is used as the link + text. When set to a string, the provided string is used as the link text. + +* **`baselevel`**: + Base level for headers. + + Default: `1` + + The `baselevel` setting allows the header levels to be automatically adjusted to + fit within the hierarchy of your html templates. For example, suppose the + Markdown text for a page should not contain any headers higher than level 3 + (`<h3>`). The following will accomplish that: + + >>> text = ''' + ... #Some Header + ... ## Next Level''' + >>> from markdown.extensions.toc import TocExtension + >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)]) + >>> print html + <h3 id="some_header">Some Header</h3> + <h4 id="next_level">Next Level</h4>' * **`slugify`**: - Callable to generate anchors based on header text. Defaults to a built in - `slugify` method. The callable must accept two arguments, the first - contains the text content of the header and the second contains the - separator. It should then return a string which will be used as the anchor - text. + Callable to generate anchors. -* **`title`**: - Title to insert in the Table of Contents' `<div>`. Defaults to `None`. + Default: `markdown.extensions.headerid.slugify` -* **`anchorlink`**: - Setting to `True` will cause the headers link to themselves. Default is - `False`. + In order to use a different algorithm to define the id attributes, define and + pass in a callable which takes the following two arguments: -* **`permalink`**: - Set to `True` to have this extension generate a Sphinx-style permanent links - near the headers (for use with Sphinx stylesheets). + * `value`: The string to slugify. + * `separator`: The Word Separator. + + The callable must return a string appropriate for use in HTML `id` attributes. + +* **`separator`**: + Word separator. Character which replaces whitespace in id. + Default: `-`
\ No newline at end of file diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt index ca25a46..dee771b 100644 --- a/docs/release-2.6.txt +++ b/docs/release-2.6.txt @@ -96,6 +96,19 @@ Backwards-incompatible Changes be used instead. See the [documentation](reference.html#extension-configs) for a full explaination of the current behavior. +* The [HeaderId][hid] Extension is pending deprecation and will raise a + **`PendingDeprecationWarning`** in version 2.6. The extension will be + deprecated in version 2.7 and raise an error in version 2.8. Use the + [Table of Contents][TOC] Extension instead, which offers most of the + features of the HeaderId Extension and more (support for meta data is missing). + + Extension authors who have been using the `slugify` and `unique` functions + defined in the HeaderId Extension should note that those functions are now + defined in the Table of Contents extension and should adjust their import + statements accordingly (`from markdown.extensions.toc import slugify, unique`). + +[hid]: extensions/headerid.html + What's New in Python-Markdown 2.6 --------------------------------- @@ -110,15 +123,29 @@ What's New in Python-Markdown 2.6 [Meta-Data]: extensions/meta_data.html [YAML]: http://yaml.org/ -* The [TOC] Extension has been refactored. Significantly, the extension now - assigns the Table of Contents to the `toc` attrbibute of the Markdown class - regardless of whether a "marker" was found in the document. Third party - frameworks no longer need to insert a "marker," run the document through - Markdown, then extract the TOC from the document. +* The [Table fo Contents][TOC] Extension has been refactored and some new features + have been added. See the documentation for a full explaination of each feature + listed below: + + * The extension now assigns the Table of Contents to the `toc` attribute of + the Markdown class regardless of whether a "marker" was found in the document. + Third party frameworks no longer need to insert a "marker," run the document + through Markdown, then extract the TOC from the document. - Additionaly, the TOC Extension is now a "registered extension." Therefore, - when the `reset` method of the Markdown class is called, the `toc` attribute - on the Markdown class is cleared (set to an empty string). + * The TOC Extension is now a "registered extension." Therefore, when the `reset` + method of the Markdown class is called, the `toc` attribute on the Markdown + class is cleared (set to an empty string). + + * When the `marker` config option is set to an empty string, the parser completely + skips the process of searching the document for markers. This should save parsing + time when the TOC Extension is being used only to assign ids to headers. + + * A `separator` config option has been added allowing users to override the + separator character used by the slugify function. + + * A `baselevel` config option has been added allowing users to set the base level + of headers in their documents (h1-h6). This allows the header levels to be + automatically adjusted to fit within the hierarchy of an html template. [TOC]: extensions/toc.html |