Explicit Table of Contents

This section discusses how you can control the table of contents by explicitly declaring them in .opensquiggly files.


Explicit table of contents management is done by placing a “.opensquiggly” file within each folder containing your documents.

Format of .opensquiggly Files

For any given folder in the document tree, if a .opensquiggly file is present in that folder, then the .opensquiggly ordering technique is used, otherwise the numerical prefix method is used. The two techniques can be mixed-and-matched together within a document tree, though generally it is recommended that an author pick one technique or the other and use it consistently throughout the document tree.

The .opensquiggly file is a simple text file format with lines of the form:


The table of contents items are rendered in the order in which they appear in the file.

Example Using .opensquiggly Files

The /docs folder contains

(folder) overview
(folder) reference
(folder) proposals
(folder) images
(file)   index.md
(file)   .opensquiggly

/docs/index.md contains

Here is some system documentation.

/docs/.opensquiggly contains


The /docs/overview folder contains

(file) history.md
(file) concepts.md
(file) devenv-setup.md
(file) index.md
(file) .opensquiggly

/docs/overview/index.md contains

Here is some overview documentation.

/docs/overview/.opensquiggly contains

devenv-setup.md=Development Environment Setup

The /docs/reference folder contains

(file) db-schema.md
(file) folder-layout.md
(file) index.md

/docs/reference/.opensquiggly contains

db-schema.md=Database Schema
folder-layout.md=Folder Layout

The /docs/reference/index.md contains

Here is some reference documentation

The /docs/proposals folder contains

(file) external-content.md
(file) mapped-pages.md
(file) system-ids.md
(file) index.md

/docs/proposals/.opensquiggly contains

external-content.md=External Content
mapped-pages.md=Mapped Pages
system-ids.md=System Identifiers

The /docs/proposals/index.md contains

Here are specifications for work proposals.

The /docs/images folder contains


Assume the /docs folder is connected via a mapped topic page named Documentation.

Now the Navigator renders the following navigation of child topic pages.

Documentation -> Overview  -> History
                              Development Environment Setup
                 Reference -> Database Schema
                              Folder Layout
                 Proposals -> External Content
                              Mapped Pages
                              System Identifiers