Alternative to VuePress

Is your feature request related to a problem? Please describe.

I’m trying to generate a documentation website depending on the folder hierarchy somewhat like VuePress. I have two main problem, first with Nuxt Routing not allowing me to view file in sub-folder and one with querying the API to generate a sidebar depending on the Markdown documents hierarchy. Here’s a codesandbox to follow along: https://codesandbox.io/s/nuxt-content-vuepress-alternative-ij4ip

Describe the solution you’d like

Let’s start with the the routing. I would like every file inside the content folder to have a route automatically generated for a specific path, somewhat like VuePress. For exemple, my pages/documentation/_slug.vue should be able to point to any of these files:

content/
    - README.md (work) // => `/documentation/`
    - test/ // => `/documentation/test`
        - README.md (does not work) // => `/documentation/test`
        - test.md (does not work) // => `/documentation/test/test`

As you can see from the sandbox, clicking on the links in the sidebar does not work and results in a 404 because I think Nuxt is trying to route to a pages/ (vue file) instead of a content/ (markdown file). It would be nice to be able to specify a path to generate sub-route for every root-folder of the content/ folder, maybe ? Also, the README.md or index.* should automatically be picked up to become the default route for each folder.

The second problem I have is with the API. It was partially corrected by Nuxt-content 1.4 by allowing to query nested folder and the deep: true config option, but I feel the API could be a little more like the Table of content one. For exemple, I would like to be able to query only to a depth of 2 or 3 to generate a manageable sidebar. Maybe an option to query page bellow the current on or from the root could be intresting too. For example, if I’m on test/README.md I could do await $content({ deep: true, depth: 2, fromRoot: false }).fetch(); and receive test.md and 2 level of children (if any). Also the result would need to be able to be grouped by path, although I could probably use lodash for this, but the critical path is that each route have a key that give their level just like headings in the TOC. This would allow use to style our sidebar in a similar manner to the TOC example: :class="{ 'sidebar-depth--2': link.depth === 2, 'sidebar-depth--3': link.depth === 3 }"

[mrleblanc101]

Thanks @mathe42. I’ll look into this. @azrikahar This wouldn’t work as the folder depth is not fixed.

[azrikahar]

The reason why it’s not working is because in your pages/documentation/_slug.vue file, the following line:

const document = await $content(params.slug || "README", {
  deep: true
}).fetch();

particularly $content(params.slug || "README") (disregarding the options.deep for now), it just means it is fetching the / directory of content, not nested ones like content/XXX. Hence why the “README” can map to content/README.md, but slugs like “test” will map to content/test directory, thus returning an array since you specified the options.deep config. This is evident when we try to go https://ij4ip.sse.codesandbox.io/documentation/test. It will work (as in not showing 404), but the reason we can’t see anything is because now “document” is an Array, so this line <nuxt-content :document="document"></nuxt-content> in your pages/documentation/_slug.vue will not work properly when you pass in an Array instead of Object.

@mathe42 is spot on there. The dynamic nested routes are actually the crucial ingredient in this scenario. @mrleblanc101 can you kindly try the following steps for it to work in your case? (I have tested this myself, but I can try to upload this exact sample to a repo if you really want)

1. Move pages/documentation/_slug.vue file to pages/documentation/_category/_slug.vue.

2. For line 32-34 in the newly moved _slug.vue file, change it from

   // old code
   const document = await $content(params.slug || "README", {
     deep: true
   }).fetch();
   

   into

   // new code
   const { category, slug } = params
   const document = await $content(category, slug || 'README').fetch()
   

3. Change the :to of NuxtLink in line 7, from

   // old code
   <NuxtLink :to="link.path">{{ link.slug }}</NuxtLink>
   

   into

   // new code
   <NuxtLink
        :to="
           link.slug === 'README'
           ? `/documentation${link.dir}`
           : `/documentation${link.path}`
       "
   >
       {{ link.slug }}
   </NuxtLink>
   

This 3rd step is to make it so README will use dir, which is / instead of /README in the URL. We have to append /documentation since your current ones doesn’t have it. Perhaps it can be set as a publicRuntimeConfig (Refer here) rather than hardcoding it.

Do let me know if it works for you 😃