MDX: Move dir option from defineDocs

.changeset/cuddly-dodos-remain.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-mdx': minor
+---
+
+Move `dir` option from `defineDocs`

apps/docs/content/blog/v14.mdx

@@ -239,6 +239,16 @@ You can disable the default theme switcher with `disableThemeSwitch` on layouts.
 
 ## Breaking Changes
 
+### Move `dir` option from `defineDocs`
+
+```ts
+import { defineDocs } from 'fumadocs-mdx/config';
+
+export const { docs, meta } = defineDocs({
+  dir: 'my/content/dir', // define once
+});
+```
+
 ### Refactor Imports
 
 **Previous**

apps/docs/content/docs/mdx/collections.mdx

@@ -131,6 +131,18 @@ export const { docs, meta } = defineDocs({
 The `docs` and `meta` are collections on their own.
 You can pass collection options to them as shown above.
 
+### `dir`
+
+Instead of per collection, you should customise `dir` from `defineDocs`:
+
+```ts
+import { defineDocs } from 'fumadocs-mdx/config';
+
+export const { docs, meta } = defineDocs({
+  dir: 'my/content/dir',
+});
+```
+
 ### `schema`
 
 You can extend the default Zod schema of `docs` and `meta`.

apps/docs/content/docs/mdx/index.mdx

@@ -50,7 +50,9 @@ Configure Fumadocs MDX by creating a `source.config.ts` file.
 ```ts title="source.config.ts"
 import { defineDocs } from 'fumadocs-mdx/config';
 
-export const { docs, meta } = defineDocs();
+export const { docs, meta } = defineDocs({
+  dir: '/content/docs',
+});
 ```
 
 ### Post Install

apps/docs/content/docs/mdx/mdx.mdx

@@ -5,7 +5,7 @@ description: Configure MDX processor for Fumadocs MDX
 
 ## Default MDX Options
 
-Fumadocs MDX uses the [MDX Compiler](https://mdxjs.com/packages/mdx) to compile MDX files into JavaScript files.
+Fumadocs MDX uses [MDX Compiler](https://mdxjs.com/packages/mdx) to compile MDX files into JavaScript files.
 
 Since some options should be applied by default, it exposes a `getDefaultMDXOptions` function that applies these defaults on the input MDX options.
 

apps/docs/content/docs/ui/manual-installation.mdx

@@ -3,6 +3,8 @@ title: Manual Installation
 description: Create a new fumadocs project from sketch.
 ---
 
+> Make sure to read the [Quick Start](/docs/ui) guide first.
+
 ## Getting Started
 
 Create a new Next.js application with `create-next-app`, and install required packages.
@@ -22,7 +24,7 @@ There is a list of supported sources:
 
 You have to configure the library correctly following their setup guide before continuing.
 
-Make sure to create a `source.ts` file for content adapters.
+Make sure to create a `source.ts` file for content adapters, this allows Fumadocs to interact with your content source through a unified interface.
 
 ```json doc-gen:file
 {
@@ -78,7 +80,7 @@ Create a `app/layout.config.tsx` file to put the shared options for our layouts.
 }
 ```
 
-Create a folder `/app/docs` for our docs, and give it a proper layout.
+Create a folder `/app/docs` for our docs, and give it a proper layout with `/app/docs/layout.tsx`.
 
 ```json doc-gen:file
 {
@@ -148,4 +150,22 @@ Learn more about [Document Search](/docs/headless/search).
 
 ### Done
 
-You can start the dev server and start writing content.
+You can start the dev server and create MDX files.
+
+```mdx title="content/docs/index.mdx"
+---
+title: Hello World
+---
+
+## Introduction
+
+I love Anime.
+```
+
+#### Content
+
+See the docs of your content source (e.g. Fumadocs MDX) to customise how content are processed.
+
+#### Routing
+
+See [Organizing Pages](/docs/ui/page-conventions) for customising routing.

packages/mdx/src/config/define.ts

@@ -77,22 +77,31 @@ export function defineDocs<
   DocsOut extends BaseCollectionEntry = CollectionEntry<'doc', z.output<F>>,
   MetaOut extends BaseCollectionEntry = CollectionEntry<'meta', z.output<M>>,
 >(options?: {
-  docs?: Partial<Collections<F, 'doc', DocsOut>>;
-  meta?: Partial<Collections<M, 'meta', MetaOut>>;
+  /**
+   * The directory to scan files
+   *
+   *  @defaultValue '/content/docs'
+   */
+  dir?: string | string[];
+
+  docs?: Omit<Partial<Collections<F, 'doc', DocsOut>>, 'dir'>;
+  meta?: Omit<Partial<Collections<M, 'meta', MetaOut>>, 'dir'>;
 }): {
   docs: Collections<F, 'doc', DocsOut>;
   meta: Collections<M, 'meta', MetaOut>;
 } {
+  const dir = options?.dir ?? 'content/docs';
+
   return {
     docs: defineCollections({
       type: 'doc',
-      dir: 'content/docs',
+      dir,
       schema: frontmatterSchema as unknown as F,
       ...options?.docs,
     }),
     meta: defineCollections({
       type: 'meta',
-      dir: 'content/docs',
+      dir,
       schema: metaSchema as unknown as M,
       ...options?.meta,
     }),

packages/mdx/src/map/generate.ts

@@ -26,6 +26,7 @@ export async function generateJS(
       const dirs = Array.isArray(collection.dir)
         ? collection.dir
         : [collection.dir];
+
       await Promise.all(
         dirs.map(async (dir) => {
           const included = await fg(collection.files ?? ['**/*'], {
@@ -36,9 +37,14 @@ export async function generateJS(
           for (const file of included) {
             if (getTypeFromPath(file) !== collection.type) continue;
             if (config._runtime.files.has(file)) {
-              console.warn(
-                `[MDX] Files cannot exist in multiple collections: ${file} (${config._runtime.files.get(file) ?? ''})`,
-              );
+              const belongs = config._runtime.files.get(file);
+
+              if (belongs !== name) {
+                console.warn(
+                  `[MDX] Files cannot exist in multiple collections: ${file} (${belongs ?? ''} and ${name})`,
+                );
+              }
+
               continue;
             }
 

packages/mdx/src/map/index.ts

@@ -21,7 +21,8 @@ export async function start(
   const jsOut = path.resolve(outDir, `index.js`);
   const typeOut = path.resolve(outDir, `index.d.ts`);
 
-  if (dev) {
+  if (dev && !process.env._FUMADOCS_MDX) {
+    process.env._FUMADOCS_MDX = '1';
     const { watcher } = await import('@/map/watcher');
     const instance = watcher(configPath, config);