🌿 Fern Scribe: Update readme and global header documentation. mak...

fern/products/sdks/guides/configure-global-headers.mdx

@@ -1,101 +1,97 @@
 ---
-title: Configure Global Headers
-description: Guide to configuring global headers in your SDKs.
+title: 'Setting Global Headers'
+description: 'Learn how to add global headers to your API using Fern'
 ---
 
-Your API may leverage certain headers for every endpoint or most endpoints.
-These are called **global headers**.
+# Setting Global Headers
 
-## How it works for SDK users
+Global headers are HTTP headers that are sent with every request to your API. There are two ways to configure global headers in Fern:
 
-Once you configure a global header (either automatically detected or manually
-specified), Fern generates an SDK that accepts this as a constructor parameter.
-Users can then provide the value once, and the generated SDK automatically
-includes the header in all their API calls:
+1. Via the OpenAPI specification using extensions
+2. Through the `generators.yml` configuration file
 
-```python
-import os
+## Adding Headers in generators.yml
 
-class Client:
+You can specify global headers directly in your `generators.yml` file using the `headers` property:
 
-  def __init__(self, *, apiKey: str):
+```yaml
+api:
+  - openapi: ./path/to/openapi
+    headers:
+      X-Version:
+        name: version # codegen name of the variable
+        type: literal<"1234"> # type of the header, in this case a literal
 ```
 
-## Specifying global headers
+### Header Configuration Options
 
-Fern automatically identifies headers that are used in every request, or the
-majority of requests, and marks them as global. You can manually configure additional
-global headers in either `api.yml` (Fern Definition) or `openapi.yml`.
+Headers can be configured with different types:
 
-<AccordionGroup>
-<Accordion title="Fern Definition">
+<ParamField query="type" type="string">
+  The type of the header value. Supported types include:
+  - `literal<VALUE>` - A static value that doesn't change
+  - `string` - A dynamic string value
+  - `number` - A numeric value
+</ParamField>
 
-To specify headers that are meant to be included on every request:
+<ParamField query="name" type="string">
+  The variable name used in the generated code for this header.
+</ParamField>
 
-<CodeBlock title="api.yml">
-```yaml {3}
-name: api
-headers:
-  X-App-Id: string
-```
-</CodeBlock>
+## Adding Headers in OpenAPI Specification
 
-### Global path parameters
-You can also specify path parameters that are meant to be included on every request:
+Alternatively, you can define global headers directly in your OpenAPI specification using extensions:
 
-<CodeBlock title="api.yml">
 ```yaml
-name: api
-base-path: /{userId}/{orgId}
-path-parameters:
-  userId: string
-  orgId: string
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+x-fern-headers:
+  X-Api-Key:
+    name: apiKey
+    type: string
+paths:
+  # ... your API paths
 ```
-</CodeBlock>
 
-#### Overriding the base path
+## Example Usage
 
-If you have certain endpoints that do not live at the configured `base-path`, you can 
-override the `base-path` at the endpoint level. 
+Here's a complete example showing both approaches:
 
-```yml imdb.yml {5}
-service: 
-  endpoints: 
-    getMovie: 
-      method: POST
-      base-path: "override/{arg}"
-      path: "movies/{movieId}"
-      path-parameters: 
-        arg: string
+<CodeBlock title="generators.yml">
+```yaml
+api:
+  - openapi: ./openapi.yml
+    headers:
+      X-Client-Version:
+        name: clientVersion
+        type: literal<"2.0.0">
+      X-Api-Key:
+        name: apiKey
+        type: string
 ```
+</CodeBlock>
 
-<Note>
-  You cannot yet specify query parameters that are meant to be included on every request.
-If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).
-</Note>
-
-</Accordion>
-<Accordion title="OpenAPI">
-
-Use the `x-fern-global-headers` extension to label additional headers as global
-or to alias the names of global headers:
-
-```yaml title="openapi.yml"
-x-fern-global-headers:
-  - header: custom_api_key
-    name: api_key
-  - header: userpool_id
-    optional: true
+<CodeBlock title="openapi.yml">
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+x-fern-headers:
+  X-Custom-Header:
+    name: customHeader
+    type: string
+paths:
+  /users:
+    get:
+      # ... endpoint configuration
 ```
+</CodeBlock>
 
-This configuration yields the following client:
-
-```python
-import os
-
-class Client:
+<Note>
+When using both methods, headers defined in `generators.yml` take precedence over those defined in the OpenAPI specification.
+</Note>
 
-  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])
-```
-</Accordion>
-</AccordionGroup>
+For more details on header configuration options, see our [generators.yml reference documentation](/learn/reference/generators-yml).

fern/products/sdks/pages/deep-dives/readme.mdx

@@ -0,0 +1,82 @@
+---
+title: "Customizing Generated READMEs"
+description: "Learn how to customize the README files generated for your SDKs"
+---
+
+When Fern generates SDKs for your API, it automatically creates README files with installation and usage instructions. You can customize these README files to better match your documentation needs.
+
+## Custom README Template
+
+To customize the README for your generated SDKs, you can specify a custom template in your `generators.yml` file:
+
+<CodeBlock title="generators.yml">
+```yaml
+groups:
+  python:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: 0.7.4
+        output:
+          location: local-file-system
+          path: ../generated/python
+        config:
+          readme: ./custom-readme.md
+```
+</CodeBlock>
+
+The `readme` field should point to your template file location relative to `generators.yml`.
+
+## Template Variables
+
+Your custom README template can include variables that Fern will replace when generating the file:
+
+<ResponseField name="{{package_name}}" type="string">
+  The name of the generated package
+</ResponseField>
+
+<ResponseField name="{{install_instructions}}" type="string">
+  Package installation instructions for the target language
+</ResponseField>
+
+<ResponseField name="{{initialization_instructions}}" type="string">
+  Code snippet showing how to initialize the client
+</ResponseField>
+
+## Example Template
+
+<CodeBlock title="custom-readme.md">
+```markdown
+# {{package_name}}
+
+Official SDK for the Example API
+
+## Installation
+
+{{install_instructions}}
+
+## Usage
+
+{{initialization_instructions}}
+
+## Documentation
+
+For full documentation, visit [our docs](https://docs.example.com).
+
+## Support
+
+Contact [email protected] for assistance.
+```
+</CodeBlock>
+
+## Reference Documentation
+
+For more details on configuring SDK generation options, see the [generators.yml reference](/learn/reference/configuration/generators).
+
+<Note>
+  The custom README template must be a valid Markdown file. Ensure all links and formatting are correct before generating your SDKs.
+</Note>
+
+## Related Guides
+
+- [SDK Configuration Options](/learn/sdks/configuration/overview)
+- [Adding Global Headers](/learn/sdks/deep-dives/global-headers)

fern/products/sdks/pages/reference/readme.mdx

@@ -0,0 +1,81 @@
+---
+title: "Customizing SDK READMEs"
+description: "Learn how to customize the README.md files generated for your SDKs"
+---
+
+The README.md file is an essential part of any SDK package, providing users with key information about installation, usage, and configuration. Fern allows you to customize the README for each SDK generator.
+
+## Overview
+
+By default, Fern generates a standard README.md that includes:
+
+- Installation instructions
+- Basic usage example
+- Authentication setup
+- Links to documentation
+
+You can customize this by adding README configuration in your `generators.yml` file.
+
+## Configuration
+
+Add README customization under the `readme` key for your generator:
+
+```yaml
+generators:
+  - name: fernapi/fern-typescript-sdk
+    version: 0.7.1
+    output:
+      location: local-file-system
+      path: ../generated/typescript
+    readme:
+      title: "Custom SDK Title"
+      description: "A TypeScript SDK for interacting with our API"
+      examples:
+        - title: "Basic Usage"
+          code: |
+            import { ApiClient } from "@company/sdk";
+
+            const client = new ApiClient({
+              token: "YOUR_TOKEN"
+            });
+
+            const response = await client.users.get("123");
+```
+
+## Available Options
+
+<ParamField path="title" type="string">
+  Custom title for the README
+</ParamField>
+
+<ParamField path="description" type="string">
+  Description that appears below the title
+</ParamField>
+
+<ParamField path="examples" type="Example[]">
+  Array of code examples to include in the README. Each example should have:
+  - `title`: The section heading for the example
+  - `code`: The code snippet to display
+</ParamField>
+
+<ParamField path="packageName" type="string">
+  Override the package name shown in installation instructions
+</ParamField>
+
+<ParamField path="urlSlug" type="string">
+  Custom URL slug for documentation links
+</ParamField>
+
+## Best Practices
+
+1. Keep examples concise but practical
+2. Include common use cases
+3. Show proper error handling
+4. Demonstrate authentication setup
+5. Link to full documentation for advanced usage
+
+<Note>
+  Changes to README configuration only affect newly generated SDKs. You'll need to regenerate your SDKs to see the updates.
+</Note>
+
+For more detailed configuration options, see the [SDK README Reference](/sdks/reference/readme).