Content: [@nuxt/content-theme-docs] Any way to support VuePress-like directory structures using content-theme-docs?

[dylburger]

Hi y'all,

Thank you for producing the content-theme-docs package and the associated docs. I'm trying to port a VuePress project, and got it working well with a single locale (en), with Markdown in the root of content/en directory. But I ran across an issue with Markdown files in subdirectories of my content/en locale, and I'm curious if y'all are able to handle files in subdirectories in a similar way to VuePress.

My current directory structure within content/en looks like this:

index.md
support/
  index.md

When running yarn dev and loading my server root, the content at index.md successfully loads. But when I try to load /support, no content loads. Right now it appears the slug gets passed as support, which returns an array of documents in src/pages/_slug.vue. This also raises an invalid prop warning because AppGithubLink expects a single document:

Invalid prop: type check failed for prop "document". Expected Object, got Array 
found in
---> <AppGithubLink> at node_modules/@nuxt/content-theme-docs/src/components/global/app/AppGithubLink.vue

Finally, it appears that the theme might only scan for files in the content/${locale} root, since I'm not seeing categories listed on the left of the page when I include the relevant YAML front-matter in subdirectory Markdown. e.g. I have this listed as the front-matter for /support/index.md, but see no "Support" category on build:

---
title: Getting Support
description: Pipedream Support options
position: 1
category: Support
fullscreen: false
---

Ideally, I'd like to load the Markdown at support/index.md simply by hitting the /support route. VuePress implements this as default routing, which is convenient for our use case. We have ~40 Markdown files in our docs right now, so the logical separation by subdirectory is nice. We also have internal and external links that depend on this path heirarchy, e.g. https://docs.pipedream.com/workflows/steps/code/ .

I hacked on src/pages/_slug.vue in the theme package and got a basic version of this working, but I'm curious if there's a built-in capability I'm missing for handling Markdown in subdirs.

Current dependencies:

"dependencies": {
    "@nuxt/content": "^1.5.0",
    "@nuxt/content-theme-docs": "^0.2.0",
    "@nuxtjs/axios": "^5.12.0",
    "@nuxtjs/pwa": "^3.0.0-beta.20",
    "nuxt": "^2.14.0"
  }

Thanks!

[mathe42]

Subfolders are not supported

1. In code see https://github.com/nuxt/content/blob/dev/packages/theme-docs/src/pages/_slug.vue#L34
2. In docs the part:
   > Each markdown page in the content/ directory will become a page and will be listed in the left navigation. (https://content.nuxtjs.org/themes-docs#content-1)

should be changed to something like

Each markdown page in the content/ directory (not in subdirectories) will become a page and will be listed in the left navigation.

The syntax you want is not so easy to create as you have to parse the route data and get the correct file. So you should expect a change in this package so it works for you :(

In your case just use @nuxt/content without the theme-docs...

[dylburger]

Thanks @mathe42 , that helps clarify the behavior I was seeing. I was able to get a basic version of this working by modifying [src/pages/_slug.vue] in the theme package - would y'all be open to me submitting a PR to add an option theme config for supporting this default routing behavior? e.g. in the theme config a user might add something like:

export default theme({
  defaultDirectoryRouting: true // default false. If true, loading /route fetches content at content/${locale}/route/index.md
})

I'm also happy to implement the patch on our own instance, but it feels like this kind of behavior could benefit others - this kind of routing behavior seems popular with the VuePress community so it could be a neat (optional) addition.

[benjamincanac]

@dylburger This is now supported out of the box and will be available in the next release.

Check out our docs content for a preview!

[dylburger]

@benjamincanac this is so huge, thank you for getting this out!

[benjamincanac]

Closing this since it's already done, forgot to do a PR for this one.

[benjamincanac]

The @nuxt/content-theme-docs package has been released in v0.4.0, you should be able to use subdirectories now!