Add documentation for staging and production environments (#2901)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Fern Support <[email protected]>
Co-authored-by: [email protected] <[email protected]>
Co-authored-by: Devin Logan <[email protected]>

Author: 4 people

fern/products/docs/pages/getting-started/publishing-your-docs.mdx

@@ -2,21 +2,21 @@
 title: Publishing your docs
 ---
 
-When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI.
+When you are ready for your docs to be publicly accessible, publish them using the Fern CLI. Choose one of the following approaches: publish [only to a production site](#publish-to-production), or [to separate staging and production sites](#publish-to-staging-and-production). 
 
 <Info>
   Use the [Fern Dashboard](https://dashboard.buildwithfern.com) to manage CLI access and your GitHub repository connection.
 </Info>
 
-## Usage
+## Publish to production
+
+For a single production site (no staging environment), run the following command to publish your documentation:
 
 ```bash
 fern generate --docs
 ```
 
-### Example
-
-```bash
+```bash Example
 fern generate --docs
 [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
 [docs]: ✓ All checks passed
@@ -26,8 +26,9 @@ fern generate --docs
 └─
 ```
 
-### Usage in GitHub Actions
-To automate the publishing process, you can use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. 
+<Accordion title="Automate publishing process">
+
+Use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. 
 
 <Steps>
 <Step title="Generate token">
@@ -66,14 +67,124 @@ jobs:
 ```
 </Step>
 </Steps>
+</Accordion>
+
+## Publish to staging and production
+
+To preview changes on a staging site before publishing to production, define [multiple instances](/learn/docs/configuration/site-level-settings#instances-configuration) in your `docs.yml` file. Once you configure multiple instances, you must use the `--instance` flag when publishing.
+
+<Steps>
+<Step title="Configure instances">
+
+Add both staging and production URLs to your `docs.yml` file. Don't include `https://` in the URLs.
+
+```yaml docs.yml
+instances:
+  - url: plantstore-prod.docs.buildwithfern.com
+  - url: plantstore-staging.docs.buildwithfern.com
+```
+</Step>
+<Step title="Publish to a specific instance">
+
+Use the `--instance` flag to publish to a specific environment:
+
+```bash
+# Publish to staging
+fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
+
+# Publish to production
+fern generate --docs --instance plantstore-prod.docs.buildwithfern.com
+```
+
+After publishing, both instances will appear in the [Fern Dashboard](https://dashboard.buildwithfern.com).
+
+</Step>
+</Steps>
+
+<Accordion title="Automate publishing process">
+
+Use GitHub Action workflows to automatically deploy to staging on every push, while keeping production deployments manual.
+
+<Steps>
+<Step title="Generate token">
+<Markdown src="/snippets/fern-token.mdx" />
+</Step>
+<Step title="Add token as a secret">
+Add the token as a [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `FERN_TOKEN`.
+</Step>
+<Step title="Set up automatic staging deployment workflow">
+
+This workflow automatically publishes to your staging instance when changes are pushed to the `main` branch:
+
+```yaml .github/workflows/publish-staging.yml maxLines=7
+name: Publish Staging Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Fern
+        run: npm install -g fern-api
+
+      - name: Validate configuration
+        run: fern check
+
+      - name: Publish to Staging
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: fern generate --docs --instance plantstore-staging.docs.buildwithfern.com
+```
+</Step>
+<Step title="Set up manual production deployment workflow">
+
+This workflow allows you to manually trigger a production deployment from the GitHub Actions UI:
+
+```yaml .github/workflows/publish-production.yml maxLines=7
+name: Publish Production Docs
+
+on:
+  workflow_dispatch:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Fern
+        run: npm install -g fern-api
+
+      - name: Validate configuration
+        run: fern check
+
+      - name: Publish to Production
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: fern generate --docs --instance plantstore-prod.docs.buildwithfern.com
+```
+
+To deploy to production, go to the **Actions** tab in your GitHub repository, select the workflow, and click **Run workflow**.
+</Step>
+</Steps>
+</Accordion>
 
 ## Hosting 
 
 When you publish your docs, Fern takes care of hosting them for you. You can also [publish your docs to a custom domain](/docs/preview-publish/setting-up-your-domain). 
 
 ### Self-hosting your docs
 
-If you need access to your docs offline or would like to host your docs on your own server, Fern [offers that option as well](/docs/self-hosted/overview). Self-hosted docs have limited access to certain features (including Ask Fern and analytics). 
+If you need access to your docs offline or would like to host your docs on your own server, Fern [offers that option as well](/docs/self-hosted/overview). Self-hosted docs have limited access to certain features (including Ask Fern and analytics).
 
 ## Unpublishing your docs
 
@@ -93,4 +204,4 @@ navigation: []
 
 Publish the updated configuration by running `fern generate --docs`. This will remove all content from your site, and users visiting any page will see a 404 error.
 </Step>
-</Steps>
+</Steps>