docs: update contributor guides for custom docs site

.env.example

@@ -1,26 +1,22 @@
 # Content Indexer Environment Variables
 # Copy this file to .env.local and fill in your actual values
+# If you are not sure where to find these values, ask the docs team.
 
-# ============================================================================
 # GitHub API (Required for SDK indexer and production mode)
-# ============================================================================
-# Get a token at: https://github.com/settings/tokens
 # Permissions needed: public_repo (read access to public repositories)
 GH_TOKEN=your_github_token_here
 
-# ============================================================================
 # Redis / Upstash KV (Required for all indexers)
-# ============================================================================
 # Used to store path indices and navigation trees
-# Get these from your Upstash dashboard: https://console.upstash.com/
 KV_REST_API_URL=your_kv_url_here
 KV_REST_API_TOKEN=your_kv_token_here
 
-# ============================================================================
 # Algolia (Required for all indexers)
-# ============================================================================
 # Used for search indexing
-# Get these from your Algolia dashboard: https://www.algolia.com/
 ALGOLIA_APP_ID=your_app_id_here
 ALGOLIA_ADMIN_API_KEY=your_admin_api_key_here
 
+# Docs site (Required for preview mode)
+# Get these from the docs site team
+DOCS_SITE_API_KEY=site_api_key_here
+DOCS_SITE_URL=site_url_here

CONTRIBUTING.md

@@ -2,6 +2,17 @@
 
 Thank you for your interest in contributing to Alchemy's documentation! This guide will help you get started with the contribution process.
 
+## Architecture Overview
+
+Alchemy's documentation is split across two repositories:
+
+| Repository | Description |
+|---|---|
+| [`alchemyplatform/docs`](https://github.com/alchemyplatform/docs) (this repo) | Content repository — MDX pages, API specs (OpenAPI/OpenRPC), navigation config, and content indexing |
+| [`OMGWINNING/docs-site`](https://github.com/OMGWINNING/docs-site) (private) | Site repository — custom Next.js application that renders the content |
+
+As a content contributor, you only need to work in **this repo**. The docs site fetches content from here via the GitHub API and caches it in Redis. When changes are merged to `main`, the live site is automatically revalidated.
+
 ## Getting Started
 
 1. Fork the repository
@@ -11,15 +22,20 @@ Thank you for your interest in contributing to Alchemy's documentation! This gui
    git remote add upstream https://github.com/alchemyplatform/docs.git
    ```
 4. Install dependencies: `pnpm i`
-5. Create a new branch: `git checkout -b feature/your-feature-name`
+5. Create a new branch: `git checkout -b initials/your-feature-name`
+
+> \[!INFO]
+> Alchemy employees do not need to create their own fork!
 
 ### Documentation Types
 
 #### Written Documentation
 
-* Located in `content/docs/`
+* Located in `content/`
 * Written in MDX format
-* Update `docs.yml` when adding/moving pages
+* Update `content/docs.yml` when adding, removing, or moving pages
+
+For available MDX components and syntax, see the [MDX Features Reference](MDX_FEATURES.md).
 
 #### API Documentation
 
@@ -42,21 +58,32 @@ Thank you for your interest in contributing to Alchemy's documentation! This gui
 > \[!TIP]
 > Use the [YAML VSCode extension](https://marketplace.cursorapi.com/items?itemName=redhat.vscode-yaml) to get some basic OpenRPC validation with Intellisense.
 
-### Account Kit Documentation
+### Smart Wallet Documentation
 
-Account Kit documentation is maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). See its [README](https://github.com/alchemyplatform/aa-sdk/blob/main/docs/README.md) for contribution guidelines.
+Smart Wallets documentation has its own [contributing guide](https://github.com/alchemyplatform/docs/blob/main/content/wallets/README.md). Additionally, Account Kit SDK references are maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk).
 
 ## Making Changes
 
 If you are not an [Alchemy Employee](#alchemy-employees), you will need to create your own fork.
 
 1. Fork the repo (if you haven't already)
 2. Make your changes
-3. Test locally using `pnpm dev`
+3. Run linting: `pnpm run lint`
 4. Commit your changes
 5. Push to your fork
 6. Create a pull request to the upstream
 
+### Previewing Changes
+
+This is a content-only repository — there is no local dev server. Instead, users can preview branch changes before merging via the preview link generated on each PR. Alchemy contributors can also preview local content using the following command:
+
+```bash
+pnpm preview
+```
+
+> \[!NOTE]
+> Previewing local content requires environment variables. See `.env.example` for the required variables.
+
 ## Markdown Style Guide
 
 This project implements a modified version of the [Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) which is enforced in Eslint via [remark-lint](https://github.com/remarkjs/remark-lint). Please ensure you abide by the guidelines set there.
@@ -112,10 +139,10 @@ git push origin main
 ### Video Embeds
 
 ```markdown
-<embed 
-  src="https://alchemyapi-res.cloudinary.com/raw/upload/v1234567890/docs/section/video.webm" 
-  type="video/webm" 
-  style={{ width: '100%' }} 
+<embed
+  src="https://alchemyapi-res.cloudinary.com/raw/upload/v1234567890/docs/section/video.webm"
+  type="video/webm"
+  style={{ width: '100%' }}
 />
 ```
 
@@ -144,6 +171,5 @@ If you have any questions or need help, please open an issue in the repository.
 
 ## Resources
 
-* [Fern Documentation](https://buildwithfern.com/learn)
 * [OpenAPI Specification](https://swagger.io/specification/)
 * [OpenRPC Specification](https://spec.open-rpc.org/)

README.md

@@ -1,24 +1,51 @@
 # Alchemy Documentation
 
-This repository contains the documentation for Alchemy's APIs and services. The documentation is built using [Fern](https://buildwithfern.com/), a modern documentation platform.
+This repository contains the content and API specifications for Alchemy's developer documentation. The documentation site is a custom Next.js application hosted in a [separate private repository](https://github.com/OMGWINNING/docs-site), which consumes content from this repo via the GitHub API.
 
-The latest documentation lives on https://alchemy.docs.buildwithfern.com/home
+The production site lives at <https://alchemy.com/docs>
 
 ## Project Structure
 
 ```text
 /
 ├── src/
-│   ├── openapi/     # REST API definitions (OpenAPI)
-│   └── openrpc/     # JSON-RPC API definitions (OpenRPC)
+│   ├── openapi/           # REST API definitions (OpenAPI YAML)
+│   ├── openrpc/           # JSON-RPC API definitions (OpenRPC YAML)
+│   │   ├── alchemy/       # Alchemy-specific APIs
+│   │   └── chains/        # Chain-specific APIs (e.g., ethereum, polygon)
+│   ├── content-indexer/   # Indexer that syncs content to Redis and Algolia
+│   └── utils/             # Shared utilities for spec generation
 └── content/
-    ├── <tab>/       # Written documentation for that tab (MDX)
-    ├── api-specs/   # Dereferenced API Specs generated from definitions (gitignored)
-    └── docs.yml     # Navigation and structure config
+    ├── <tab>/             # Written documentation for each tab (MDX)
+    ├── api-specs/         # Dereferenced API specs generated from src/ (gitignored)
+    └── docs.yml           # Navigation and structure config
 ```
 
 > \[!WARNING]
-> Account Kit documentation is maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). See its [README](https://github.com/alchemyplatform/aa-sdk/blob/main/docs/README.md) for contribution guidelines.
+> Account Kit SDK references content is maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). Those files are auto-generated using TypeDoc.
+
+## How It Works
+
+This is a **content-only** repository. It does not run the docs site directly. Instead:
+
+1. Content authors write MDX files in `content/` and API specs in `src/`
+2. The [docs-site](https://github.com/OMGWINNING/docs-site) fetches content from this repo
+3. Content fetched from Github and cached in Redis (Upstash)
+4. Navigation structure is defined in `content/docs.yml` and indexed into Redis by the content indexer
+5. On merge to `main`, a GitHub Action triggers revalidation on the live site
+
+### Previewing Changes
+
+This is a content-only repository — there is no local dev server. Instead, users can preview branch changes before merging via the preview link generated on each PR. Alchemy contributors can also preview local content using the following command:
+
+```bash
+pnpm preview
+```
+
+> \[!NOTE]
+> Previewing local content requires environment variables. See `.env.example` for the required variables.
+
+This mode works by indexing your current branch's content in Redis with a branch-scoped prefix, then activating [Next.js draft mode](https://nextjs.org/docs/app/guides/draft-mode) to dynamically render the uploaded content. Since pages are rendered dynamically, page loads are slower compared to production. However, users no longer need to wait for long build times.
 
 ## Consuming Specs
 
@@ -38,6 +65,7 @@ Each individual API spec can be found via a simple URL pattern:
 ### Prerequisites
 
 * [pnpm](https://pnpm.io/)
+* Node.js 22.x (install via [asdf](https://asdf-vm.com/) or [mise](https://mise.jdx.dev/))
 
 ### Installation
 
@@ -54,17 +82,11 @@ Each individual API spec can be found via a simple URL pattern:
    pnpm i
    ```
 
-## Development
-
-### Local Development
+### Environment Variables
 
-Start the development server:
+Certain operations (previewing, indexing) require environment variables for Redis and Algolia. See `.env.example` for the required variables.
 
-```bash
-pnpm dev
-```
-
-This will start a local server with live reloading. Visit `http://localhost:3020` to view the documentation.
+## Development
 
 ### Building API Specs
 
@@ -76,6 +98,12 @@ pnpm run generate
 
 This will generate all specs as dereferenced json files in the `content/api-specs` directory.
 
+To watch for changes during development:
+
+```bash
+pnpm run generate:watch
+```
+
 ### Validation
 
 You can validate both OpenAPI and OpenRPC using these commands:
@@ -95,12 +123,21 @@ pnpm run validate
 
 The project uses several linting tools to ensure code quality and consistency:
 
-* **ESLint**: For JavaScript and TypeScript code linting
+* **ESLint**: For JavaScript, TypeScript, and MDX code linting
 * **Prettier**: For code formatting
 * **Remark**: For Markdown/MDX linting
 * **TypeScript**: For type checking
 
-You can find the appropriate commands for running each in `package.json`
+```bash
+# Run all linters
+pnpm run lint
+
+# Auto-fix issues
+pnpm run lint:fix
+
+# Check for broken links
+pnpm run lint:broken-links
+```
 
 #### Enforcement
 
@@ -128,7 +165,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## Resources
 
-* [Fern Documentation](https://buildwithfern.com/learn)
+* [MDX Features Reference](MDX_FEATURES.md)
 * [OpenAPI Specification](https://swagger.io/specification/)
 * [OpenRPC Specification](https://spec.open-rpc.org/)
 

content/api-reference/data/data-overview.mdx

@@ -7,14 +7,6 @@ layout: overview
 hide-toc: true
 ---
 
-<style>
-  {`
-      .fern-card {
-        font-size: 14px;
-      }
-    `}
-</style>
-
 The Data APIs give you fast, reliable access to blockchain data without running your own indexing infrastructure. Whether you're building wallets, NFT platforms, analytics dashboards, or DeFi apps, the Data APIs save you time and engineering costs by offering pre-transformed, production-ready data.
 
 ## Components of the Data APIs

content/api-reference/introduction/api-overview.mdx

@@ -7,14 +7,6 @@ layout: overview
 hide-toc: true
 ---
 
-<style>
-  {`
-    .fern-card {
-    font-size: 14px;
-    }
-    `}
-</style>
-
 <CardGroup cols={4}>
   <Card title="Node API" icon="fa-solid fa-diagram-project" href="/docs/reference/node-api-overview">
     Low-level JSON-RPC for reading & writing blockchain data.

content/wallets/CONTRIBUTING.md

@@ -223,7 +223,8 @@ Ensure you are using aa-sdk version 3.x or later...
 
 **Highlighting**:
 
-* Use [Fern highlighting](https://buildwithfern.com/learn/docs/writing-content/components/code-blocks) to focus on critical parts
+* Use code highlighting to focus on critical parts
+  * Designate highlighted lines using brackets, ex: {4,10-13}
 * Use snippets for common configuration to avoid duplication
 
 ***