From e54b2e90a806c14cef70898f7ae53a1ae2fc5040 Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Tue, 7 Oct 2025 15:11:04 -0400
Subject: [PATCH] clarify generators.yml for fern def

---
 .../api-def/pages/project-structure.mdx       | 18 +------
 fern/products/sdks/project-structure.mdx      | 25 +--------
 .../generators-yml-project-structure.mdx      | 51 +++++++++++++++++++
 3 files changed, 53 insertions(+), 41 deletions(-)
 create mode 100644 fern/snippets/generators-yml-project-structure.mdx

diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx
index f6a952794..961c24c42 100644
--- a/fern/products/api-def/pages/project-structure.mdx
+++ b/fern/products/api-def/pages/project-structure.mdx
@@ -43,23 +43,7 @@ determinism.
 
 ### `generators.yml`
 
-The `generators.yml` file points to your API definition and [specifies which SDKs to generate](/sdks/overview/project-structure).
-
-```yaml title="generators.yml"
-# Your API definition
-api: 
-  specs: 
-    - openapi: ./openapi-1.yml
-
-# SDK generators
-groups:
-  ts-sdk:
-    generators:
-      - name: fernapi/fern-typescript-sdk
-        version: <Markdown src="/snippets/version-number-ts.mdx"/>
-        github:
-          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
-```
+<Markdown src="/snippets/generators-yml-project-structure.mdx" />
 
 ### API definition file
 
diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx
index f5d2146b3..848ce13ed 100644
--- a/fern/products/sdks/project-structure.mdx
+++ b/fern/products/sdks/project-structure.mdx
@@ -56,30 +56,7 @@ Every time you run a fern CLI command, the CLI downloads itself at the correct v
 
 ### `generators.yml`
 
-The `generators.yml` file points to your API definition and specifies which SDKs to generate.
-
-```yaml title="generators.yml"
-# Your API definition
-api: 
-  specs: 
-    - openapi: ./openapi-1.yml
-
-# SDK generators
-groups:
-  ts-sdk:
-    generators:
-      - name: fernapi/fern-typescript-sdk
-        version: <Markdown src="/snippets/version-number-ts.mdx"/>
-        github:
-          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
-  
-  python-sdk:
-    generators:
-      - name: fernapi/fern-python-sdk
-        version: <Markdown src="/snippets/version-number-python.mdx"/>
-        github:
-          repository: your-organization/python-sdk-repo # Location of Python SDK
-```
+<Markdown src="/snippets/generators-yml-project-structure.mdx" />
 
 <Info title="Examples"> 
   See Cohere's [`generators.yml` file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) and Vapi's [`generators.yml` file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml).
diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx
new file mode 100644
index 000000000..cac0a7661
--- /dev/null
+++ b/fern/snippets/generators-yml-project-structure.mdx
@@ -0,0 +1,51 @@
+The `generators.yml` file specifies which SDKs to generate. **For OpenAPI**, it also points to the location of your spec. **For Fern Definition**, Fern automatically detects your spec when your `definition/` folder is at the same level as `generators.yml`.
+
+<Tabs>
+<Tab title="OpenAPI">
+
+```yaml title="generators.yml"
+# Your API definition
+api: 
+  specs: 
+    - openapi: ./openapi-1.yml
+
+# SDK generators
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: <Markdown src="/snippets/version-number-ts.mdx"/>
+        github:
+          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
+  
+  python-sdk:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: <Markdown src="/snippets/version-number-python.mdx"/>
+        github:
+          repository: your-organization/python-sdk-repo # Location of Python SDK
+```
+</Tab>
+<Tab title="Fern Definition">
+
+```yaml title="generators.yml"
+# No API reference needed – Fern auto-detects spec
+
+# SDK generators
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: <Markdown src="/snippets/version-number-ts.mdx"/>
+        github:
+          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
+  
+  python-sdk:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: <Markdown src="/snippets/version-number-python.mdx"/>
+        github:
+          repository: your-organization/python-sdk-repo # Location of Python SDK
+```
+</Tab>
+</Tabs>
\ No newline at end of file