Table of Contents
⇐ 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: