feat(docs): add Stainless vs Fern comparison pages as hidden resources (#1817)

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

Author: 4 people

.vale.ini

@@ -27,6 +27,7 @@ Microsoft.Dashes = NO
 Microsoft.Foreign = NO
 Microsoft.Plurals = NO
 Microsoft.Quotes = NO # Mostly just picks up code
+Microsoft.Auto = NO
 
 # Not relevant for Fern audience
 Microsoft.GeneralURL = NO
@@ -42,6 +43,7 @@ Microsoft.Headings = NO
 Microsoft.HeadingPunctuation = NO
 Microsoft.Hyphens = NO
 Microsoft.We = NO
+Microsoft.Avoid = NO
 
 
 

.vale/styles/FernStyles/Acronyms.yml

@@ -91,3 +91,12 @@ exceptions:
   - PNG
   - AAA
   - ARIA
+  - SSO
+  - RAG
+  - SCIM
+  - CDN
+  - VPC
+  - RSS
+  - FDR 
+  - SSR
+  - SSG

fern/products/docs/docs.yml

@@ -292,4 +292,11 @@ navigation:
         path: ./pages/developer-tools/vale.mdx  
       - page: View Markdown
         path: ./pages/developer-tools/view-markdown.mdx
-  
+  - section: Resources
+    collapsed: true
+    hidden: true
+    contents:
+      - page: Stainless vs. Fern
+        path: ./pages/resources/stainless-comparison.mdx
+        slug: stainless-comparison
+  

fern/products/docs/pages/resources/stainless-comparison.mdx

@@ -0,0 +1,163 @@
+---
+title: Stainless vs. Fern
+description: Comprehensive enterprise feature comparison between Stainless Docs and Fern Docs platforms
+---
+
+## Overview
+
+Fern is [production-ready](/learn/docs/getting-started/quickstart) with stable APIs and comprehensive enterprise features. Stainless is in [early access](https://www.stainless.com/docs/docs-platform/) with breaking changes expected before 1.0.
+
+Choose Fern for enterprise requirements, regulated industries, or production-critical documentation. Choose Stainless for simple documentation with Git-only workflows and Astro preference.
+
+| Capability | Fern | Stainless |
+|------------|------|-----------|
+| **Maturity** | Production-ready, stable APIs | Early access, breaking changes expected |
+| **Authoring** | [Visual editor](/learn/docs/writing-content/fern-editor) + Git | Git only |
+| **Enterprise features** | [RBAC](/learn/docs/authentication/rbac), [SSO](/learn/docs/authentication/sso), [versioning](/learn/docs/configuration/what-is-docs-yml) | None |
+| **API testing** | [Interactive explorer](/learn/docs/api-references/api-explorer/overview) | None |
+| **Deployment** | Cloud + [full-stack self-hosted](/learn/docs/self-hosted/overview) | Static files only |
+
+## Detailed feature comparison
+
+<AccordionGroup>
+<Accordion title="Platform maturity and stability" defaultOpen={true}>
+
+Fern is production-ready with stable APIs and backward compatibility. Stainless is in early access with [expected breaking changes](https://www.stainless.com/docs/docs-platform/) before reaching 1.0.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Production status** | ✅ [Production-ready](/learn/docs/getting-started/quickstart), stable | ⚠️ Early access with breaking changes expected |
+| **Enterprise deployments** | ✅ Widely deployed ([ElevenLabs](https://elevenlabs.io/docs), [Webflow](https://developers.webflow.com), [Hume AI](https://dev.hume.ai)) | ⚠️ Limited production usage |
+
+</Accordion>
+
+<Accordion title="Content authoring and governance">
+
+Stainless uses Git-based workflows for all content authoring. Fern supports both Git workflows and the [Fern Editor](/learn/docs/writing-content/fern-editor), a browser-based visual editor for technical writers, product managers, and support teams.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Visual editor** | ✅ [Fern Editor](/learn/docs/writing-content/fern-editor) with GitHub App integration | ❌ None |
+| **Content format** | ✅ [MDX](/learn/docs/writing-content/markdown) with React components | ✅ MDX/Markdoc |
+| **Reusable content** | ✅ [Snippets system](/learn/docs/writing-content/reusable-snippets) | ✅ Markdown partials |
+
+</Accordion>
+
+<Accordion title="API reference and interactive testing">
+
+Stainless doesn't provide an interactive testing environment. Fern's [API Explorer](/learn/docs/api-references/api-explorer/overview) enables in-browser endpoint testing with automatic credential injection.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **API Explorer** | ✅ [Full playground](/learn/docs/api-references/api-explorer/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key), WebSocket, and audio streaming support | ❌ None |
+| **SDK documentation** | ✅ [Multi-language support](/learn/docs/api-references/sdk-snippets) | ✅ Language-specific pages |
+| **API spec formats** | ✅ [OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern](/learn/docs/api-references/generate-api-ref) | ⚠️ OpenAPI + Stainless config only |
+
+</Accordion>
+
+<Accordion title="RBAC, versioning, and multi-product support">
+
+Stainless doesn't currently offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/what-is-docs-yml) capabilities for complex API portfolios.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **RBAC** | ✅ [Audience-based content filtering](/learn/docs/authentication/rbac) for internal vs. public sites | ❌ None |
+| **API versioning** | ✅ [Multi-version support](/learn/docs/configuration/what-is-docs-yml) with availability states and per-version content | ❌ None |
+| **Multi-product sites** | ✅ [Multiple products](/learn/docs/configuration/what-is-docs-yml) in unified documentation | ⚠️ Basic tabs (Guides/Reference) |
+
+</Accordion>
+
+<Accordion title="AI-powered search and assistance">
+
+Stainless offers RAG-based search. Fern provides additional AI features including [guidance documents](/learn/ask-fern/), [custom knowledge sources](/learn/ask-fern/), [MCP server](/learn/docs/ai-features/mcp-server), and analytics for operational control.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **AI chatbot** | ✅ [Ask Fern](/learn/ask-fern/) with Claude/Cohere, [guidance documents](/learn/ask-fern/), and custom knowledge sources | ✅ RAG-based Q&A |
+| **MCP server** | ✅ [Auto-generated](/learn/docs/ai-features/mcp-server) for AI coding assistants | ❌ None |
+| **AI analytics** | ✅ [Content gap identification](/learn/ask-fern/) and insights | ❌ None |
+| **Search** | ✅ Vector search with faceting by language, product, version | ⚠️ Metadata-driven with basic faceting |
+| **LLM-friendly format** | ✅ [/llms.txt and /llms-full.txt](/learn/docs/seo/llms-txt) | ✅ .md extension on URLs |
+
+</Accordion>
+
+<Accordion title="Authentication and security">
+
+Stainless's [authentication](https://www.stainless.com/docs/docs-platform/advanced/stainless-authentication/) focuses on API keys for their service. Fern's [WorkOS integration](/learn/docs/authentication/sso) provides enterprise SSO (SAML/OIDC) for end-user authentication with role-based content visibility.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Enterprise SSO** | ✅ [WorkOS](/learn/docs/authentication/sso) (SAML/OIDC/SCIM) with [RBAC](/learn/docs/authentication/rbac) | ❌ None |
+| **Authenticated pages** | ✅ [Login-protected documentation](/learn/docs/authentication/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key) | ⚠️ API keys for Stainless service only |
+
+</Accordion>
+
+<Accordion title="Hosting and deployment">
+
+Stainless [deploys static files](https://www.stainless.com/docs/docs-platform/hosting-and-deploys/) to hosting platforms. Fern's [self-hosted Docker](/learn/docs/self-hosted/overview) includes a full stack (PostgreSQL, MinIO, MeiliSearch) for on-premises deployment.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Cloud hosting** | ✅ [Vercel with AWS VPC backend](/learn/docs/getting-started/publishing-your-docs) | ✅ Cloudflare (default) |
+| **Self-hosted** | ✅ [Full-stack Docker](/learn/docs/self-hosted/overview) (PostgreSQL, S3/MinIO, MeiliSearch) | ❌ Static files only |
+| **Custom domains** | ✅ [Full support](/learn/docs/getting-started/setting-up-your-domain) | ✅ Full support |
+
+</Accordion>
+
+<Accordion title="Redirects, SEO, and large-site operations">
+
+Stainless doesn't currently document redirect capabilities. Fern's [redirect system](/learn/docs/seo/redirects) supports pattern matching and hundreds of rules for content migrations and reorganization.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Redirects** | ✅ [299+ rules](/learn/docs/seo/redirects) with pattern matching (`:slug`, `:splat`) | ❌ None |
+| **SEO optimization** | ✅ [Meta tags, JSON-LD, RSS, OG images, Twitter cards](/learn/docs/seo/metadata) | ✅ Basic meta tags |
+| **Sitemap & robots.txt** | ✅ [Automatic generation](/learn/docs/seo/metadata) | ✅ Automatic (assumed) |
+
+</Accordion>
+
+<Accordion title="Analytics and observability">
+
+Stainless doesn't currently document built-in analytics capabilities. Fern provides [analytics integrations](/learn/docs/integrations/overview) for page visits, search queries, AI chat insights, and user journeys.
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Analytics integrations** | ✅ [PostHog](/learn/docs/integrations/analytics/posthog), [Google Analytics](/learn/docs/integrations/analytics/google), [Segment](/learn/docs/integrations/analytics/segment), [Mixpanel](/learn/docs/integrations/analytics/mixpanel) ([full list](/learn/docs/integrations/overview)) | ❌ None |
+| **Documentation insights** | ✅ Search analytics, AI chat tracking, content gap identification | ❌ None |
+| **Performance monitoring** | ✅ Vercel Analytics | ⚠️ Cloudflare Analytics |
+
+</Accordion>
+
+<Accordion title="Extensibility and integrations">
+
+Both platforms support [customization](https://www.stainless.com/docs/docs-platform/customization/styles-and-fonts/), but Fern provides deeper enterprise integrations including [MCP server](/learn/docs/ai-features/mcp-server) for AI assistants, webhooks, and [30+ pre-built components](/learn/docs/writing-content/components/overview).
+
+| Feature | Fern Docs | Stainless Docs |
+|---------|-----------|----------------|
+| **Component library** | ✅ [30+ pre-built components](/learn/docs/writing-content/components/overview) ([Accordion](/learn/docs/writing-content/components/accordions), [Callout](/learn/docs/writing-content/components/callouts), [Card](/learn/docs/writing-content/components/cards), [Tabs](/learn/docs/writing-content/components/tabs), etc.) | ⚠️ Standard library |
+| **Custom components** | ✅ [React components](/learn/docs/writing-content/custom-react-components) with [custom CSS/JS](/learn/docs/customization/custom-css-js) | ✅ Astro components with custom CSS/JS |
+| **Third-party integrations** | ✅ [Algolia, PostHog, WorkOS, Intercom, etc.](/learn/docs/integrations/overview) | ⚠️ Astro ecosystem |
+| **Developer APIs** | ✅ [MCP server](/learn/docs/ai-features/mcp-server), webhooks, FDR API | ❌ None |
+
+</Accordion>
+</AccordionGroup>
+
+## Technology stack comparison
+
+| Component | Fern Docs | Stainless Docs |
+|-----------|-----------|----------------|
+| **Frontend** | Next.js (React) with SSR/SSG | Astro (static site generator) |
+| **Backend** | Node.js/Express (FDR) on AWS VPC | Stainless API service |
+| **Database** | PostgreSQL | Not applicable (static) |
+| **Cache** | Redis, Vercel KV (Upstash) | Cloudflare CDN |
+| **Storage** | S3 (AWS/MinIO) | Not applicable (static) |
+| **Search** | Algolia, MeiliSearch (self-hosted) | Metadata-driven indexing |
+| **Vector database** | TurboPuffer | None |
+| **AI** | Bedrock, Claude, Cohere | RAG with LLM (provider not specified) |
+| **Authentication** | WorkOS | API keys (for Stainless service) |
+| **CDN** | Cloudflare + Vercel Edge | Cloudflare |
+| **Analytics** | PostHog | None |
+| **Deployment** | Vercel, Docker (self-hosted) | Cloudflare, any static host |
+
+
+