aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/extensions/toc.txt73
1 files changed, 43 insertions, 30 deletions
diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt
index 260129c..2204a9c 100644
--- a/docs/extensions/toc.txt
+++ b/docs/extensions/toc.txt
@@ -10,16 +10,17 @@ Table of Contents
Summary
-------
-Adds a Table of Contents to a Markdown document.
+The Table of Contents extension generates a Table of Contents from a Markdown
+document and adds it into the resulting HTML document.
-This extension is included with the Markdown library since version 2.0.
+This extension is included in the standard Markdown library.
Syntax
------
-Place a marker in the document where you would like the table of contents to
+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:
+marker. The marker defaults to `[TOC]` so the following document:
[TOC]
@@ -43,33 +44,45 @@ would generate the following output:
Usage
-----
-From the Python interpreter:
+See [Extensions](./index.html) for general extension usage, specify `toc`
+as the name of the extension.
- >>> html = markdown.markdown(some_text, extensions=['toc'])
+See the [Library Reference](../reference.html#extensions) for information about
+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]``.
-* **slugify**: Callable to generate anchors based on header text. Defaults to a
- built in ``slugify`` method. The callable must accept one argument which
- contains the text content of the header and return a string which will be
- used as the anchor text.
-* **title**: Title to insert in TOC ``<div>``. Defaults to ``None``.
-* **anchorlink**: Set to ``True`` to have the headers link to themselves.
- Default is ``False``.
-* **permalink**: Set to ``True`` to have this extension generate Sphinx-style
- permanent links near the headers (for use with Sphinx stylesheets).
-
-If a 'marker' is not found in the document, then the toc is available as an
-attribute of the Markdown class. This allows one to insert the toc elsewhere
-in their page template. For example:
-
- >>> text = '''
- # Header 1
-
- ## Header 2
- '''
- >>> md = markdown.Markdown(extensions=['toc'])
- >>> html = md.convert(text)
- >>> render_some_template(context={'body': html, 'toc': md.toc})
+* **marker**:
+ Text to find and replace with the Table of Contents. Defaults
+ to `[TOC]`.
+
+ If a `marker` is not found in the document, then the Table of Contents is
+ available as an attribute of the Markdown class. This allows one to insert
+ the Table of Contents elsewhere in their page template. For example:
+
+ >>> text = '''
+ # Header 1
+
+ ## Header 2
+ '''
+ >>> md = markdown.Markdown(extensions=['toc'])
+ >>> html = md.convert(text)
+ >>> render_some_template(context={'body': html, 'toc': md.toc})
+
+* **slugify**:
+ Callable to generate anchors based on header text. Defaults to a built in
+ `slugify` method. The callable must accept one argument which contains the
+ text content of the header and return a string which will be used as the
+ anchor text.
+
+* **title**:
+ Title to insert in the Table of Contents' `<div>`. Defaults to `None`.
+
+* **anchorlink**:
+ Setting to `True` will cause the headers link to themselves. Default is
+ `False`.
+
+* **permalink**:
+ Set to `True` to have this extension generate a Sphinx-style permanent links
+ near the headers (for use with Sphinx stylesheets).
+