diff options
Diffstat (limited to 'docs/extensions/toc.txt')
| -rw-r--r-- | docs/extensions/toc.txt | 92 |
1 files changed, 67 insertions, 25 deletions
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 |