How to make Docus only handle routes under /docs in a Nuxt 4 project?

[PauloAFBarbosa]

Hi everyone!

I’ve been working with Docus and could use a bit of help.

I managed to set up a standalone Docus project to serve documentation, and it worked great. Now I’m trying to integrate it into my existing Nuxt 4 website — but I’ve run into a problem: Docus seems to be taking over all the routing.

No matter what route I visit, it tries to resolve it from the /content directory (looking for a Markdown file).

My question:
Is there a way to configure Docus so it only handles routes under a specific path, like /docs?

For example:

• /docs → /content/index.md
• /docs/folder1/page1 → /content/folder1/page1.md

Basically, I’d like Docus to serve content only under /docs, and leave the rest of the Nuxt routes untouched.

I’ve already checked the Nuxt Content and Docus documentation, but couldn’t find anything about scoping Docus to a specific route.

Any tips or workarounds would be really appreciated, thanks a lot!

[megasanjay]

+1 for this. With the new Nuxt team backing I was hoping we could use docus directly in our nuxt application. An example for this possibility would be great!

We just need /docs to be handled by docus with content/docs/xx.md as the pages. Not sure who we can ping for some clarification on this.

[oneminch]

You can put your Markdown inside /content/docs. That way it maps to /docs.

In the Docus code base, the route is configured using the content.config.ts file as with any Nuxt Content based project:

// This is a simplified version of it

const cwd = joinURL(options.rootDir, 'content')   // resolves to '/content' of your project

export default defineContentConfig({
  /* ... */
  docs: defineCollection({
    type: 'page',
    source: {
      cwd,
      include: '**',
      exclude: ['index.md'],
    },
    schema: /* ... */
  })
})

According to the Nuxt Content docs, there is a prefix property under the source key that allows you to add a route prefix (e.g. /docs). Docus itself is using it for i18n (e.g. /en & /fr prefixes). I don't know how you would configure it from your side though.

[larbish]

It's achieved this way on https://content.nuxt.com, you can have a check at how we've handled it overriding the nuxt content configuration: https://github.com/nuxt/content/blob/main/docs/content.config.ts#L13

Is it enough in your case?

[oneminch]

@larbish I'm not the one who opened the issue but I’m curious. Does creating a content config in the consuming app override all the original config of Docus or merge it together?

[larbish]

@oneminch It's merging and overriding (if you create the same collection).

[jd-solanki]

It'll be great if docus can support existing Nuxt 4 projects but I'm not sure how SEO and other configured options like SEO will co-exist for both docs and existing project. E.g. I tried to add docus to my Nuxt v4 project then it started configuring SEO itself and it might override my own SEO config.

[megasanjay]

Yeah. Thanks for this info! I think a example would be helpful for the task of normal app (+ adding docus as a layer for /docs/** only.) I tried it with the comments above but i couldn't get the index page to use the normal pages directory index. It seems to look for the docus index.md file