DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:odt:tutorials:toc

ODT Plugin homepage

ODT Tutorials: Table Of Contents

This page shows examples and gives some help for creating a table of contents with the ODT plugin. First, let us define some example wiki page content to work with in the following:

tocexamplepage.txt
====== Chapter 1 Headline ======
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.1 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.1 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.2 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.3 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.2 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.3 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
====== Chapter 2 Headline ======
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
====== Chapter 3 Headline ======
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

The minimum syntax

The minimum syntax to create a table of contents is:

{{odt>toc}}

Try extending the example wiki page like this:

{{odt>toc}}

====== Chapter 1 Headline ======

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
...

Using the minimum odt>toc syntax tag will create a table of contents according to the ODT plugin's configuration settings. After export the table of contents on the first page of the document should look like this:

But why are the page numbers all wrong? The ODT plugin only enumerates all entries in the table of contents. The table of contents needs to be updated after the export to get the correct page numbers! To update the table of contents, right click on the table of contents and choose “Update Index or Table of Contents” from the context menu, see image below:

After updating the table of contents you should see the correct page numbers like in the image below:

Showing a preview

You might have already noticed that the ODT plugin's table of contents does not generate any output in the browser window. This can make editing a document uncomfortable because it is easy to forget if and where the table of contents has been placed on the page if you cannot see it. To solve this problem a little placeholder can be displayed to remind you that a table of contents will be inserted at that place in the document after export to ODT. Just set the configuration option index_in_browser from hide to display placeholder. Now, the example page shows a little message box reminder:

Syntax tag options

The toc syntax tag comes along with a set of options. If an option is specified then it overwrites the setting from the ODT plugin's configuration. If an option is omited then the value from the configuration is used.

Avoiding a pagebreak

A pagebreak after the table of contents can be avoided using the pagebreak option. The following syntax will suppress the pagebreak after the table of contents:

{{odt>toc:pagebreak=false;}}

And this code will enable the pagebreak explicitly:

{{odt>toc:pagebreak=true;}}

Limiting the depth of the ToC

To limit the depth of the table of contents use the option maxlevel. Set the syntax tag in the example page to:

{{odt>toc:maxlevel=2;}}

After export the table of contents should look like this:

Changing the title

The standard heading for the table of contents in english language is “Table of Contents”. If you want a different title then specify it with the title option. Here are some examples:

{{odt>toc:title=My ToC;}}
{{odt>toc:title=This awaits you...;}}

Setting the leader sign

The leader sign is the sign in a table of contents which fills up the space between an table of contents entry and the page number. It can be set using the leader_sign option (do not forget the underscore!). Set the syntax tag in the example page to:

{{odt>toc:leader_sign=-;}}

After export the table of contents should look like this:

Indentation

The indentation of the different table of contents levels can be set using the indents option. It requires a list of comma separated values. Each value is representing the absolute indent of a level in centimeters. The first value specifies the indent for level one, the second specifies the indent for level 2 and so on. The configuration default value is “0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5”. So every level is indented a half centimeter more than the previous one. Set the syntax tag in the example page to:

{{odt>toc:indents=0,1,2,3,4,5,6,7,8,9,10;}}

After export the table of contents should look like this:

You can also give some levels the same indentation. Set the syntax tag in the example page to:

{{odt>toc:indents=0,2,2,2,2,2,2,2,2,2,2;}}

After export the table of contents should look like this:

Styling

The styling of the table of contents can be changed using the options styleH and styleL1 to styleL10. Both options expect CSS code to specify the style. The styleH option is used to specify the style for the title and the styleL1 option is used to specify the style for level 1 entries. The styleL2 option is used to specify the style for level 2 entries and so on.

First, let us give our title a red color. Set the syntax tag in the example page to:

{{odt>toc:styleH="color: red;";}}

After export the table of contents should look like this:

Now, let us give different colors for the first 3 levels also. Set the syntax tag in the example page to:

{{odt>toc:styleH="color: red;";styleL1="color: chartreuse;";styleL2="color: coral;";styleL3="color: royalblue;";}}

After export the table of contents should look like this:

Ok, let us have a look at a more serious example. The syntax tag

{{odt>toc:styleLH="font-weight: bold;";styleL1="font-weight: bold;font-size: 16pt;";styleL2="font-style: italic;";styleL3="font-style: italic;";}}

produces the following look:

Numbered Headings

If numbered headings are enabled then the enumeration of the headings will only get visible after an update of the table of contents, also see section The minimum syntax. The following picture shows a table of contents with numbered headings after an update:

Chapter Indexes

Chapter indexes work exactly in the same way as the toc syntax tag. So the minimum syntax for a chapter index is:

{{odt>chapter-index}}

Let us insert a chapter index syntax tag after the beginning of each new chapter. After that our example page should look like this:

tocexamplepage.txt
{{odt>toc}}
 
====== Chapter 1 Headline ======
 
{{odt>chapter-index}}
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.1 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.1 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.2 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
==== Chapter 1.1.3 Headline ====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.2 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
===== Chapter 1.3 Headline =====
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
====== Chapter 2 Headline ======
 
{{odt>chapter-index}}
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 
====== Chapter 3 Headline ======
 
{{odt>chapter-index}}
 
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

The chapter index of the first chapter should look like this:

plugin/odt/tutorials/toc.txt · Last modified: 2017-04-12 20:40 by LarsDW223