feat: create workflow for generating previews and publishing docs using fern

.eslintrc

@@ -68,8 +68,9 @@
     {
       "files": ["**/*.mdx"],
       "extends": ["plugin:mdx/recommended"],
-      "settings": {
-        "import/extensions": ["off", "ignorePackages"]
+      "rules": {
+        "import/extensions": ["off", "ignorePackages"],
+        "react/jsx-no-undef": "off"
       }
     }
   ]

.github/workflows/preview-fern-docs.yml

@@ -0,0 +1,61 @@
+name: Generate Fern Docs Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout aa-sdk
+        uses: actions/checkout@v4
+
+      - name: Download Alchemy Docs Repo
+        run: |
+          rm -rf docs-site && \
+          curl -L -f -H "Authorization: token ${{ secrets.DOCS_GITHUB_TOKEN }}" \
+            -o docs.tar.gz https://api.github.com/repos/alchemyplatform/docs/tarball/main && \
+          tar xzf docs.tar.gz && \
+          mv alchemyplatform-docs-* docs-site && \
+          rm docs.tar.gz
+
+      - name: Copy docs to docs-site/account-kit and cd into docs-site
+        run: |
+          mkdir -p docs-site/account-kit
+          cp -r docs/* docs-site/account-kit/
+
+      - name: Insert Account Kit docs.yml into docs-site/fern/docs.yml
+        run: |
+          cd docs-site
+          account-kit/scripts/insert-docs.sh
+
+      - name: Install Fern CLI
+        run: npm install -g fern-api
+
+      - name: Generate preview URL
+        id: generate-docs
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: |
+          cd docs-site
+          OUTPUT=$(fern generate --docs --preview 2>&1) || true
+          echo "$OUTPUT"
+          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
+          echo "preview_url=$URL" >> $GITHUB_OUTPUT
+
+      - name: Comment Preview URL in PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '## 🌿 Documentation Preview\n\n| Name | Preview | Updated (UTC) |\n| :--- | :------ | :------ |\n| **Alchemy Docs** | [🔗 Visit Preview](${{ steps.generate-docs.outputs.preview_url }}) | ' + new Date().toLocaleString('en-US', { month: 'short', day: 'numeric', year: 'numeric', hour: 'numeric', minute: '2-digit', hour12: true }) + ' |\n\n>'
+            });

.github/workflows/publish-fern-docs.yml

@@ -0,0 +1,43 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
+    steps:
+      - name: Checkout aa-sdk
+        uses: actions/checkout@v4
+
+      - name: Download Alchemy Docs Repo
+        run: |
+          rm -rf docs-site && \
+          curl -L -f -H "Authorization: token ${{ secrets.DOCS_GITHUB_TOKEN }}" \
+            -o docs.tar.gz https://api.github.com/repos/alchemyplatform/docs/tarball/main && \
+          tar xzf docs.tar.gz && \
+          mv alchemyplatform-docs-* docs-site && \
+          rm docs.tar.gz
+
+      - name: Copy docs to docs-site/account-kit and cd into docs-site
+        run: |
+          mkdir -p docs-site/account-kit
+          cp -r docs/* docs-site/account-kit/
+
+      - name: Insert Account Kit docs.yml into docs-site/fern/docs.yml
+        run: |
+          cd docs-site
+          account-kit/scripts/insert-docs.sh
+
+      - name: Install Fern CLI
+        run: npm install -g fern-api
+
+      - name: Publish Docs
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: |
+          cd docs-site
+          fern generate --docs --log-level debug

.gitignore

@@ -129,3 +129,5 @@ Pods
 
 vendor
 
+# pulled in from alchemyplatform/docs
+docs-site/

aa-sdk/core/package.json

@@ -38,6 +38,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/aa-sdk/core",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/aa-sdk/core",
     "clean": "rm -rf ./dist",
     "test": "vitest",
     "test:run": "vitest run"

aa-sdk/ethers/package.json

@@ -37,6 +37,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/aa-sdk/ethers",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/aa-sdk/ethers",
     "clean": "rm -rf ./dist",
     "test": "vitest",
     "test:run": "vitest run"

account-kit/core/package.json

@@ -41,6 +41,7 @@
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "clean": "rm -rf ./dist",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/core",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/core",
     "test": "vitest --passWithNoTests",
     "test:run": "vitest run --passWithNoTests"
   },

account-kit/infra/package.json

@@ -35,6 +35,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/infra",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/infra",
     "clean": "rm -rf ./dist",
     "test": "vitest",
     "test:run": "vitest run"

account-kit/react-native/package.json

@@ -30,6 +30,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/react-native",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/react-native",
     "clean": "rm -rf ./dist"
   },
   "devDependencies": {

account-kit/react/package.json

@@ -57,6 +57,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/react",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/react",
     "clean": "rm -rf ./dist",
     "test": "vitest --passWithNoTests",
     "test:run": "vitest run --passWithNoTests"

account-kit/rn-signer/package.json

@@ -43,6 +43,7 @@
     "build": "yarn typecheck",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/react-native-signer",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/react-native-signer",
     "prepare": "bob build"
   },
   "keywords": [

account-kit/signer/package.json

@@ -35,6 +35,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/signer",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/signer",
     "clean": "rm -rf ./dist",
     "test": "vitest --passWithNoTests",
     "test:run": "vitest run --passWithNoTests"

account-kit/smart-contracts/package.json

@@ -47,6 +47,7 @@
     "build:esm": "tsc --project tsconfig.build.json --outDir ./dist/esm",
     "build:types": "tsc --project tsconfig.build.json --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
     "docs:gen": "node ../../doc-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/smart-contracts",
+    "fern:gen": "node ../../fern-gen/dist/esm/cli.js generate --in ./src/index.ts --out ../../docs/pages/reference/account-kit/smart-contracts",
     "clean": "rm -rf ./dist",
     "test": "vitest",
     "test:run": "vitest run"

doc-gen/src/commands/generate.ts

@@ -24,7 +24,7 @@ export async function generate(options: GenerateOptions) {
   const sourceFilePath = path.resolve(process.cwd(), options.in);
   const outputFilePath = path.resolve(process.cwd(), options.out);
   logger.info(
-    `Generating documentation for ${sourceFilePath} and ouputing to ${outputFilePath}`
+    `Generating documentation for ${sourceFilePath} and outputting to ${outputFilePath}`
   );
 
   const sourceFile = getSourceFile(sourceFilePath);

docs/README.md

@@ -0,0 +1,64 @@
+# Account Kit Documentation
+
+This repository contains the documentation for Account Kit that gets published to [alchemy.com/docs](https://alchemy.com/docs) which is built using [Fern](https://buildwithfern.com/learn/docs/getting-started/overview).
+
+The contents are automatically merged with [Alchemy's Official Docs repo](https://github.com/alchemyplatform/docs) to create seamless updates without needing to make changes separately in that repo.
+
+## Structure
+
+- `docs.yml` - The main configuration file that defines the documentation structure and sidebar navigation
+- `pages/` - Directory containing the documentation markdown files
+- `images/` - Directory containing images used in the documentation
+
+## Making Updates
+
+### Docs Content
+
+To add or modify documentation content:
+
+- Add/edit markdown files in the `pages/` directory
+- Follow the existing markdown formatting conventions
+- You may use any [existing Fern components](https://buildwithfern.com/learn/docs/content/components/overview) without import statements
+
+To add new pages to navigation:
+
+- Update the `navigation` section in `docs.yml`
+- Reference markdown files from `pages/` by path using `../account-kit/pages`
+
+### Images
+
+To add new images:
+
+- Place image files in the `images/` directory
+- Use descriptive filenames
+- Reference images from the `images/` directory in markdown using `images/account-kit/filename.png`
+- You may use [markdown syntax or `img` tags](https://buildwithfern.com/learn/docs/content/write-markdown#images)
+
+### SDK References
+
+SDK Refernces are automatically generated from relevant projects within the monorepo via `fern-gen`. In the root, run:
+
+```shell
+yarn fern-gen
+```
+
+### Local Development
+
+**TBD:** Currently this would require distributing a GitHub Token to access Alchemy Docs repo. Will remove this requirement once those docs go live.
+
+### Preview Changes
+
+1. Create a pull request with your changes
+2. The CI will automatically generate a preview URL in the PR comments
+3. Review the preview to ensure your changes appear as expected
+
+### Publishing
+
+Documentation changes are automatically published to [alchemy.com/docs](https://alchemy.com/docs) when merged to the `main` branch.
+
+## Technical Details
+
+- The `scripts/insert-docs.sh` script handles:
+  - Moving images to the correct location in the main docs site
+  - Inserting Account Kit documentation configuration into the main docs site config
+- Documentation is built and published using [Fern CLI](https://buildwithfern.com/learn/cli-reference/overview#setting-up-docs)

docs/components/icons/ClockForwardIcon.tsx

@@ -0,0 +1,19 @@
+import { SVGProps } from "react";
+
+export const ClockForwardIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width={20}
+    height={20}
+    fill="none"
+    {...props}
+  >
+    <path
+      stroke="#E82594"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={1.5}
+      d="m12.097 12-3-1V6.819m8 3.181a8 8 0 1 0-1.07 4m-1.124-4.878 2 2 2-2"
+    />
+  </svg>
+);

docs/components/icons/DotsIcon.tsx

@@ -0,0 +1,16 @@
+import { SVGProps } from "react";
+
+export const DotsIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width={20}
+    height={20}
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="#E82594"
+      d="M6.046 10a2 2 0 1 1-4 0 2 2 0 0 1 4 0ZM12 10a2 2 0 1 1-4 0 2 2 0 0 1 4 0ZM18.089 10a2 2 0 1 1-4 0 2 2 0 0 1 4 0Z"
+    />
+  </svg>
+);

docs/components/icons/ExpoIcon.tsx

@@ -0,0 +1,10 @@
+import { SVGProps } from "react";
+
+export const ExpoIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg width="24" height="22" viewBox="0 0 24 22" fill="none" {...props}>
+    <path
+      d="M11.39 8.269c.19-.277.397-.312.565-.312.168 0 .447.035.637.312 1.49 2.03 3.95 6.075 5.765 9.06 1.184 1.945 2.093 3.44 2.28 3.63.7.714 1.66.269 2.218-.541.549-.797.701-1.357.701-1.954 0-.407-7.958-15.087-8.759-16.309C14.027.98 13.775.683 12.457.683h-.988c-1.315 0-1.505.297-2.276 1.472C8.392 3.377.433 18.057.433 18.463c0 .598.153 1.158.703 1.955.558.81 1.518 1.255 2.218.54.186-.19 1.095-1.684 2.279-3.63 1.815-2.984 4.267-7.029 5.758-9.06z"
+      fill="#E82594"
+    />
+  </svg>
+);

docs/components/icons/InfraIcon.tsx

@@ -0,0 +1,16 @@
+import { SVGProps } from "react";
+
+export const InfraIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width={20}
+    height={20}
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="#E82594"
+      d="M6.389 12.778c-1.775 0-3.283-.621-4.525-1.864C.62 9.672 0 8.164 0 6.39c0-.309.022-.617.067-.926.045-.309.12-.605.226-.888a.823.823 0 0 1 .288-.38c.121-.081.258-.14.41-.178a.904.904 0 0 1 .46.009.952.952 0 0 1 .423.254l2.96 2.938 2.384-2.385-2.927-2.938A.951.951 0 0 1 4.028 1c.037-.15.098-.287.184-.408a.865.865 0 0 1 .374-.289A3.95 3.95 0 0 1 5.47.067C5.776.022 6.083 0 6.39 0c1.775 0 3.283.621 4.525 1.863 1.243 1.243 1.864 2.751 1.864 4.526 0 .469-.044.905-.133 1.31-.088.404-.22.795-.397 1.173l6.038 6.004c.466.464.699 1.032.699 1.704 0 .672-.232 1.24-.696 1.706a2.315 2.315 0 0 1-1.705.699 2.295 2.295 0 0 1-1.708-.716l-6.004-6.021c-.392.17-.79.3-1.195.392a5.807 5.807 0 0 1-1.288.138Zm0-1.667c.486 0 .972-.072 1.459-.217a4.11 4.11 0 0 0 1.334-.678l6.9 6.9c.135.135.304.2.508.194a.72.72 0 0 0 .508-.212.69.69 0 0 0 .203-.508.69.69 0 0 0-.203-.509l-6.9-6.882c.313-.385.543-.823.69-1.313.149-.491.223-.99.223-1.497 0-1.232-.44-2.323-1.32-3.272-.88-.948-1.995-1.413-3.342-1.395L8.857 4.13c.2.201.301.436.301.703 0 .268-.1.502-.301.703l-3.32 3.321c-.202.2-.436.301-.704.301a.964.964 0 0 1-.703-.301L1.722 6.449c.003 1.426.482 2.56 1.438 3.4.956.842 2.032 1.262 3.229 1.262Z"
+    />
+  </svg>
+);

docs/components/icons/PointerIcon.tsx

@@ -0,0 +1,16 @@
+import { SVGProps } from "react";
+
+export const PointerIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width={20}
+    height={20}
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="#E82594"
+      d="M1.966 9.16h.966c.273 0 .503.093.688.278a.935.935 0 0 1 .278.689.934.934 0 0 1-.278.688.935.935 0 0 1-.688.278h-.966a.935.935 0 0 1-.688-.278.934.934 0 0 1-.278-.688c0-.274.093-.503.278-.689a.935.935 0 0 1 .688-.277Zm1.642 5.217.676-.676a.885.885 0 0 1 .676-.278c.258.008.483.1.676.278a.985.985 0 0 1 .302.688.9.9 0 0 1-.277.688l-.677.676a.899.899 0 0 1-.688.278.985.985 0 0 1-.966-.978.885.885 0 0 1 .278-.676Zm.676-7.824-.676-.676A.885.885 0 0 1 3.33 5.2c.008-.258.1-.483.278-.677a.985.985 0 0 1 .688-.301.899.899 0 0 1 .688.277l.677.676a.899.899 0 0 1 .277.689.985.985 0 0 1-.302.688c-.193.177-.418.27-.676.278a.885.885 0 0 1-.676-.278Zm11.494 11.59-3.912-3.911-.724 2.173a.426.426 0 0 1-.181.254.466.466 0 0 1-.555-.012.481.481 0 0 1-.182-.266L8.148 9.475a.701.701 0 0 1 .012-.387c.04-.128.1-.233.18-.314.081-.08.186-.14.315-.18a.701.701 0 0 1 .386-.013l6.955 2.077a.427.427 0 0 1 .253.181.51.51 0 0 1 .085.278c0 .096-.024.189-.073.277a.378.378 0 0 1-.241.182l-2.173.772 3.863 3.864c.193.193.29.419.29.676a.927.927 0 0 1-.29.676l-.58.58a.927.927 0 0 1-.675.29.927.927 0 0 1-.677-.29ZM8.728 4.332v-.966c0-.273.092-.503.277-.688a.935.935 0 0 1 .688-.278c.274 0 .503.093.688.278a.935.935 0 0 1 .278.688v.966a.935.935 0 0 1-.278.688.935.935 0 0 1-.688.278.935.935 0 0 1-.688-.278.935.935 0 0 1-.278-.688Zm4.998.845.7-.7a.944.944 0 0 1 .664-.278.9.9 0 0 1 .688.278c.178.177.27.399.278.664a.94.94 0 0 1-.253.688l-.7.725a.827.827 0 0 1-.665.278 1.033 1.033 0 0 1-.688-.278.985.985 0 0 1-.302-.688.899.899 0 0 1 .278-.689Z"
+    />
+  </svg>
+);

docs/components/icons/ReactNativeIcon.tsx

@@ -0,0 +1,22 @@
+import { SVGProps } from "react";
+
+export const ReactNativeIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg width="800px" height="800px" viewBox="0 0 15 15" fill="none" {...props}>
+    <path
+      d="M14.5 7.58387C14.5 9.24072 11.366 10.5839 7.5 10.5839C3.63401 10.5839 0.5 9.24072 0.5 7.58387C0.5 5.92701 3.63401 4.58387 7.5 4.58387C11.366 4.58387 14.5 5.92701 14.5 7.58387Z"
+      stroke="#E82594"
+    />
+    <path
+      d="M4.16589 13.7389C5.62274 14.5281 8.29645 12.4121 10.1378 9.01277C11.9791 5.61345 12.2908 2.21803 10.834 1.42888C9.37712 0.639735 6.70341 2.7557 4.86207 6.15502C3.02073 9.55434 2.70904 12.9498 4.16589 13.7389Z"
+      stroke="#E82594"
+    />
+    <path
+      d="M10.834 13.7389C9.37714 14.5281 6.70343 12.4121 4.86209 9.01277C3.02075 5.61345 2.70906 2.21803 4.16591 1.42888C5.62276 0.639735 8.29647 2.7557 10.1378 6.15502C11.9792 9.55434 12.2908 12.9498 10.834 13.7389Z"
+      stroke="#E82594"
+    />
+    <path
+      d="M6.5 7.58387C6.5 8.13615 6.94772 8.58387 7.5 8.58387C8.05228 8.58387 8.5 8.13615 8.5 7.58387C8.5 7.03158 8.05228 6.58387 7.5 6.58387C6.94772 6.58387 6.5 7.03158 6.5 7.58387Z"
+      stroke="#E82594"
+    />
+  </svg>
+);

docs/components/icons/SignerIcon.tsx

@@ -0,0 +1,19 @@
+import { SVGProps } from "react";
+
+export const SignerIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width={20}
+    height={20}
+    fill="none"
+    {...props}
+  >
+    <path
+      stroke="#E82594"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={1.5}
+      d="m10.447 18.035.619-.693c.758-.85 2.12-.74 2.732.222a1.719 1.719 0 0 0 2.598.356l1.121-1.006M4 13l3.5 3m-4-3 9.86-10.204a2.718 2.718 0 1 1 3.844 3.845L7 16.5 2 18l1.5-5Z"
+    />
+  </svg>
+);