Content: Creating a Table of Contents for All Content

[jhull]

I'm curious how to easily create a Table of Contents for all content files, divided up into sections (directories), pretty much like how it is in the Docs Theme on the left-hand sidebar. I feel like it's super-easy, but can't find any examples anywhere.

This is for a project already in production (so can't use the Nuxt Content Docs module).

On the one hand it looks like its all in the root directory of content, but then how is it organized?

[NozomuIkuta]

@jhull

I believe deep option is for you.

For your information, theme-docs creates table of contents (in the form of an object, not array) in the following way:

• Fetch all the contents with deep option in ascending order based on position in the front matter.
• Divide them into categories based on category in the front matter, with loadash.groupBy() function.

Here is source code

I hope this helps you.

[jhull]

This worked GREAT! Thanks so much...curious though, about next prev and surround. Currently using this:

    async asyncData({ $content, params }){
      const path = `/docs/${params.pathMatch || 'index'}`
      const [page] = await $content({ deep: true }).where({ path }).fetch()
      const [prev, next] = await $content('docs', { deep: true })
        .only(['title', 'slug', 'path'])
        .sortBy('position', 'asc')
        .surround(page.slug, { before: 1, after: 1 })
        .fetch()
      return { page, prev, next }
    }

And the prev and next are grabbing from different categories. Current structure looks like this:

/content
  /docs
    introduction.md (position:1)
    /getting-started
      first-01.md (position:1)
      first-02.md (position:2)
      first-03.md (position:3)

Prev and next on first-02.md gives me introduction.md for prev and first-03.md for next.

Am I supposed to have position set in sequence from beginning to end, regardless of directory structure? (So the above is position 1, position 2, position 3, position 4)? Or is there-hopefully-a better way to do it?

[NozomuIkuta]

@jhull

I'm glad to hear that it worked! 👍

And yeah, I also think it's somewhat confusing at first that relationship between position property and directory structure.

In short, as you guess, we are supposed to have position set in sequence from beginning to end.

---

If I understand it correctly based on my code reading, the situation is like the following:

• Nuxt Content internally calls fs.readdir() method (recursively) to retrieve all the file names in the content directly.
• fs.readdir() doesn't guarantee the order of file names (reference).
• As each file appears in the array returned by fs.readdir(), it is transformed and pushed to an array (database's internal behavior).
• As a result, files in database know nothing about "position" of themselves (e.g. who are neighbors).

I believe this is why authors provide position property. With this property, Nuxt Content can sort files according to information architecture, independently of physical directory structure. Indeed, without such property, we can't fetch prev/next files and have a control on the order of navigation links.

---

Or is there-hopefully-a better way to do it?

By the way, I also wish there were better way. 🤔
What we want to do is to order pages, and not numbering every single of them, right?

With current approach, the more the website grows, the harder it would likely to become to organize files/pages. FYI, I'm avoiding such situation by defining numbering rules, where I can add pages between others later (e.g. increment position by 5 for pages, by 100 for directories (categories)).

/content
    /category-1 // virtual position: 0
        /doc-1.md // position: 1
        /doc-2.md // position: 6
        /doc-3.md // position: 11
    /category-2 // virtual position: 100
        /doc-4.md // position: 101

[jhull]

Oh, that's a great idea about the numbering rules. I will definitely steal that one, and hopefully down the line there can be an easier built-in solution.

Thanks!