====== TocTweak Plugin ======

===== Examples/Usage v2=====

==== Control macro for DokuWiki built-in TOC ====

<code>
~~CLOSETOC~~         Let the TOC box initially closed
~~TOC 2-3~~          Headlines within level 2 to 3 will appear in the TOC box
~~NOTEC 2-3~~        No TOC box on the page, but set headline level parameter
~~TOC 2-3 wide~~     Widen the TOC box by assigning "wide" css class
~~TOC_HERE 2-3~~     Locate the TOC box where the macro is placed in the page
</code>

== Note ==
  * Headlines level parameter must be "//n-m//", "//n//" or "//-m"// format.
  * The built-in toc box (or %%auto-TOC%%) should be one per page, therefore more than once "''%%~~TOC_HERE~~%%''" will be ignored.

==== METATOC: Another method to show TOC (in different looks/design)====

{{ https://github.com/ssahara/dw-plugin-toctweak/raw/master/example/image2.png?200&recache|METATOC variants}}

TocTweak plugin provides following syntax to render toc block in pages where it is located in source. These are implemented as variants of basic **METATOC** syntax, and can be used multiple times in a page.

  - ''%%{{METATOC}}%%'' : Headline list with hierarchical numbers
  - ''%%{{TOC}}%%'': similar looks of DW built-in %%TOC%% box without open/close feasure.
  - ''%%{{INLINETOC}}%%'' : Headline list in rounded box
  - ''%%{{SIDETOC}}%%'' : dedicated to use in sidebar page

METATOC syntax family can render headline list of other page. It is also possible to specify starting section title, headline level range, and %%TOC%% box title.

  {{METATOC 3-3 >:wiki:syntax#Text Conversions | Text Conversions}}
  {{METATOC 3-3 >:wiki:syntax#Text Conversions |}}
  {{METATOC 2-3 >#section title}}
  {{METATOC 2-3}}

== Note ==
  * The section title may contains spaces, therefore headline level parameter must be given before "%%>%%".
  * set %%TOC%% title blank (given after "%%|%%") to remove default title -- "Table of Contents".
  * SIDETOC ignores //n-m// parameter, which will be retrieved from metadata of current page.

----

===== Examples/Usage v1=====

==== 1. Set the TOC initially closed ====

  ~~CLOSETOC~~

  * The TOC box will be initially closed state (in case the TOC is displayed in the page). This is a kind of control macro without creating any output itself.

==== 2. Set top and max level of headings displayed in the TOC====

  ~~TOC 2-4 ~~

  * Control the content of the TOC for the page. There are two numeric parameters: [[:config:toptoclevel]] and [[:config:maxtoclevel]] repectively.
  * Above example will exclude the page title (i.e. the first level 1 heading) from the TOC. Headings from level 2 to 4 included in the automatically generated Table of Contents.
  * You can tweak either top or max level of headings, for example:<code>
~~TOC 2~~
~~TOC -3~~
</code>

==== 3. move TOC position ====

  {{TOC}}

  * Move/slide the TOC box placed at top right corner to anywhere in the page. Exactly, the TOC position is changeable only vertically in the page because the macro ''%%{{TOC}}%%'' in the Wiki text is to be rendered as same as original TOC html. Maybe useful if you want to place the TOC box after the second heading in order to avoid confliction with the [[tags]] line. 

  {{TOC wide}}

  * You can add css class to the TOC div box identifed with ''%%#dw__toc%%''. Above example will apply class name "wide" to the TOC box, which is then identified as ''%%#dw__toc.wide%%'', and the TOC will be displayed with 100% width in the page. "wide" class is defined in style.css of this plugin.

  {{TOC 2-3 wide}}

  * You may give both class and heading levels parameter in this syntax. 

==== 4. inline TOC ====

  {{INLINETOC width18 3-4}} 

  * This syntax renders TOC of a page inside the page content. "width18" class is defined in all.css of this plugin.

----

===== Configuration and Settings =====

The plugin can be configured with the Configuration Manager in the admin menu. 

^''tocAllHeads''  | Store all headlines to page metadata                  |
^''tocPosition''  | Change always %%auto-TOC%% position for normal pages  |
|::: | 0: default (top-right)              |
|::: | 1: after the First Level 1 headline |
|::: | 2: after the First Level 2 headline |
|::: | 6: after the First headline         |
|::: | 9: disable %%auto-TOC%%.            |
^''toptoclevel''  | Upper level of headline which can appear in table of contents        |
^''maxtoclevel''  | Lower level of headline which can appear in table of contents        |
^''tocminheads''  | Minimum amount of headlines that determins whether the TOC is built  |

TocTweak plugin supersedes global config settings [[:config:toptoclevel]], [[:config:maxtoclevel]] and [[:config:tocminheads]]. Especially when **tocAllHeads** is on, global toptoclevel and maxtoclevel values are set to 1 and 5 respectively.

----

===== Development =====

==== Backward incompatible changes ====

**ver.2 (2018-01-08)**
  - Previously in version 1.x, ''%%{{TOC}}%%'' syntax was available to move DokuWiki %%Auto-TOC%% box from top right corner to other place inside the page. Since version 2.x, it has changed to render METATOC instead of %%Auto-TOC%%. Alternative ''%%~~TOC_HERE~~%%'' macro is available.
  - DokuWiki %%Auto-TOC%% must exist only one per page whenever it should be shown. Use of ''%%~~TOC_HERE~~%%'' macro is restricted to once in a page.

==== Change Log from github repository ====

{{rss>https://github.com/ssahara/dw-plugin-toctweak/commits/master.atom date}}

==== Bug reports and feature requests ====

Please refer to the issue tracker (link button found at near page top) for reporting issues.