---
title: "Building a table of contents with DITA versus Jekyll"
date: 2015-04-02
description: "Jekyll versus DITA   1.0 Check out Ed Marsh"
canonical_url: https://idratherbewriting.com/2015/04/02/building-a-table-of-contents-with-dita-versus-jekyll/
---
# Building a table of contents with DITA versus Jekyll
## Creating a TOC with DITA

The ditamap file in DITA is arguably the most important file in a DITA project, and it has a lot of features. Basically, the ditamap defines the table of contents for the project, which is how users navigate all the files (apart from search).

Additionally, any file that you want included in your output *must* appear in your ditamap file. Otherwise it's excluded from the build.

A project can have multiple ditamap files. You might have separate ditamap file for each output, or you could use the same ditamap file with conditional tags for multiple outputs.

In the ditamap file, you reference each topic you want included like this:

Notice how you can add attributes to the `topicref` elements. Here, if the build conditions exclude the field engineer audience, the inline_links.dita topic will be excluded.

Additionally, hierarchy is established by nesting the elements. If you want to create sublevels, you nest the topics like this:

Here the inline_links.dita topic will appear in a sublevel below keyref_links.dita. Similarly, relationship_tables.dita will appear nested below related_links.dita.

You can combine topics if you use the `chunk` attribute, like this:

Now the inserting_links.dita topic will contain inline_links.dita, related_links.dita, and keyref_links.dita files as additional sections in the same inserting_links.dita topic, rather than appearing as separate files.

If you want to include any non-DITA files, you would list them in the ditamap with a special `processing-role` attribute:

For more details on ditamap files, see my page on [ditamap files](https://idratherbewriting.com/toc_linking/mapfiles/).

## Creating a TOC with Jekyll via categories

Jekyll provides a lot of different ways to create a TOC. Since many Jekyll sites are blogs, more emphasis seems to be given to *post* sorting than *page* sorting, but Jekyll also provides an interesting paradigm to handle the TOC for pages.

You have at least two main options for create a TOC. You can add a category and weight as frontmatter in your page, and then run `for` loops to sort the content based on the category and weight.

If you want to sort pages by category, you would put a category in the frontmatter of a page, like this:

You could then use a for loop to get all pages in this category sorted by weight:

This approach may get tedious, though, especially if you want to easily shift and arrange your TOC without opening every single page to change these frontmatter values.