## What
Reorganizes the MCP (Model Context Protocol) server documentation to
clearly distinguish between multiple Airbyte MCP servers and makes all
MCP documentation discoverable through the sidebar.
Requested by AJ Steers (@aaronsteers) in [this Devin
session](https://app.devin.ai/sessions/7f61ccb7731f4009b19076fa2b5df36d).
**Problem**: The existing MCP documentation only covered one remote MCP
server (the Heroku-hosted "fast-coder" server), but there are actually
four MCP servers:
1. The new PyAirbyte MCP (local STDIO server) - the recommended option
2. The PyAirbyte Fast-Coder MCP (remote Heroku server) - for rapid code
generation
3. The Connector Builder MCP (in development)
4. The Embedded Operator MCP (existed but wasn't in the sidebar)
## How
- **Renamed** `docs/ai-agents/pyairbyte-mcp/` →
`docs/ai-agents/pyairbyte-fast-coder-mcp/` (the old remote server)
- **Created** new `docs/ai-agents/pyairbyte-mcp/README.md` with
documentation for the new local STDIO MCP server (copied from the
docstring in `airbyte/mcp/__init__.py` in the PyAirbyte repo)
- **Created** `docs/ai-agents/connector-builder-mcp/README.md` as a
stub/"coming soon" page
- **Updated** `docusaurus/sidebar-ai-agents.js` to:
- Group all four MCP servers under a "MCP Servers" category
- Add the previously hidden Embedded Operator MCP to the sidebar
- **Updated** `docs/ai-agents/README.md` to describe all four MCP
servers with clear distinctions
- **Fixed** typo: "embedded source" → "embedded search" in the
Fast-Coder MCP docs
## Review guide
1. **`docs/ai-agents/README.md`** - Verify the high-level descriptions
of each MCP server are clear and accurate
2. **`docs/ai-agents/pyairbyte-mcp/README.md`** - Review the setup
instructions for the new PyAirbyte MCP (local server). This content was
copied from the PyAirbyte repo docstring - please verify it's complete
and correct.
3. **`docs/ai-agents/pyairbyte-fast-coder-mcp/README.md`** - Verify the
renamed "Fast-Coder" MCP docs are still accurate
4. **`docusaurus/sidebar-ai-agents.js`** - Check that the sidebar
structure makes sense with all four MCP servers grouped together
5. **`docs/ai-agents/connector-builder-mcp/README.md`** - Confirm the
stub page is appropriate for the in-development server
**Key distinction to verify**: The new "PyAirbyte MCP" (local,
recommended) vs "PyAirbyte Fast-Coder MCP" (remote, for code generation)
are clearly differentiated in the docs.
## User Impact
**Positive:**
- Users can now discover all available Airbyte MCP servers in one place
- The new PyAirbyte MCP (local STDIO server) is documented and
positioned as the recommended option
- The Embedded Operator MCP is now visible in the documentation sidebar
- Clear guidance on which MCP server to use for different use cases
**Potential confusion:**
- Having two PyAirbyte-related MCP servers might initially confuse
users, but the docs clearly explain the differences
## Can this PR be safely reverted and rolled back?
- [x] YES 💚
This is purely documentation changes with no code or infrastructure
changes. Rolling back would just restore the previous documentation
structure.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
Regenerates platform documentation version 2.0 from the latest Next
(unreleased) version. This publishes all recent documentation updates
that have been made to the Next version as the stable 2.0 release.
Requested by Ian Alton (@ian-at-airbyte) via Slack thread:
https://airbytehq-team.slack.com/archives/D08FX8EC9L0/p1760747793195139?thread_ts=1760747793.195139
Link to Devin session:
https://app.devin.ai/sessions/edbc303b017445de9731080a55c04586
## How
1. Deleted the existing `version-2.0` directory from
`platform_versioned_docs/`
2. Deleted the `version-2.0-sidebars.json` from
`platform_versioned_sidebars/`
3. Temporarily removed `"2.0"` from `platform_versions.json`
4. Ran `pnpm docusaurus docs:version:platform 2.0` to regenerate version
2.0 from the current Next version
5. Verified the build succeeds locally
## Review guide
1. **New content**:
`platform_versioned_docs/version-2.0/understanding-airbyte/cdc-best-practices.md`
- Comprehensive new CDC configuration best practices guide. Review for
technical accuracy.
2. **Sidebar changes**:
`platform_versioned_sidebars/version-2.0-sidebars.json` - CDC content
reorganized under "Sync Modes" section. Verify navigation makes sense.
3. **Terminology updates** throughout various files:
- "Airbyte Open Source" → "Core"
- "Cloud Teams" → "Cloud Pro"
- "Self-Managed Community" → "Core"
- Verify these align with actual product naming conventions
4. **Content improvements** in access management, API documentation,
connector development, enterprise setup, and quickstart guides
## User Impact
Users viewing the version 2.0 platform documentation will see the latest
content updates, including:
- New comprehensive CDC best practices documentation
- Updated terminology reflecting current product names
- Improved clarity and accuracy throughout documentation
- Better organization of CDC-related content
No negative side effects expected - this is a documentation-only update.
## Can this PR be safely reverted and rolled back?
- [x] YES 💚
This is a documentation change only. Reverting would restore the
previous version 2.0 documentation content.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: ian.alton@airbyte.io <ian.alton@airbyte.io>
Co-authored-by: Octavia Squidington III <octavia-squidington-iii@users.noreply.github.com>
## What
<!--
* Describe what the change is solving. Link all GitHub issues related to
this change.
-->
This pull request updates plan names across most of the Documentation so
they're consistent with our current plan names.
## How
<!--
* Describe how code changes achieve the solution.
-->
My original plan was to convert free text to MDX variables so we only
had to make future updates to names in one place. While broadly
successful, there were numerous edge cases that made rolling this out
almost impossible. There were too many ways and places you couldn't use
variables due to a variety of limitations in Docusaurus and Airbyte's
internal MarkDown processor. Explaining how to properly use them made me
realize how prohibitively insufficient this was. In the end, I opted to
return to using free text for plan names.
Scope is now broadly reduced. This PR:
- Converts remaining instances of old plan names to new plan names. In
most cases, I replaced old plan names with new plan names directly. In
some cases, sentences were rewritten to make a bit more sense or be more
maintainable in the future.
- Removes previously added preprocessor variables from Docusaurus
configuration.
- Update Vale styles or various artifacts of content based on linter
findings.
## Review guide
<!--
1. `x.py`
2. `y.py`
-->
Spot check updated pages to ensure plan names appear appropriately. It's
probably not necessary to check every single instance in detail.
For Platform docs, changes only apply to the Next/Cloud version. After
merging, I'll regenerate 2.0 docs based on this. 1.8 and before won't be
updated.
## User Impact
<!--
* What is the end result perceived by the user?
* If there are negative side effects, please list them.
-->
People can see correct plan names in docs content.
## Can this PR be safely reverted and rolled back?
<!--
* If unsure, leave it blank.
-->
- [x] YES 💚
- [ ] NO ❌
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
Created CDC best practices guide.
## How
- Created a dedicated CDC sidebar and moved it under `Moving and
Managing Data → Connections and Streams → Sync Modes.`
- Added the new documentation file to both `v1.8` and the new platform
version.
- Updated the sidebar configuration (sidebar.js) to include the new
guide.
## Review guide
Preview:
<img width="346" height="485" alt="Screenshot 2025-10-14 at 9 51 25 AM"
src="https://github.com/user-attachments/assets/46706717-a85a-4c99-af3c-530fa7793fa3"
/>
## User Impact
None
## Can this PR be safely reverted and rolled back?
<!--
* If unsure, leave it blank.
-->
- [ ] YES 💚
- [ ] NO ❌
---------
Co-authored-by: ian-at-airbyte <ian.alton@airbyte.io>
## What
Converts the Airbyte documentation home page from a static markdown page
to a dynamic React-based page with improved visual design and
navigation. Moves "Why Airbyte?" content from home page to platform
page.
Requested by ian.alton@airbyte.io in session:
https://app.devin.ai/sessions/6441f0af52ff4f0bb03a55c3fd4252c9
## How
**Architecture Change:**
- Disabled the default Docusaurus docs plugin at root route (`docs:
false`)
- Enabled pages plugin to support standalone React pages
- Deleted `/docs/home/readme.md` and `sidebar.js`
- Created new React component at `/docusaurus/src/pages/index.js`
**New Home Page Features:**
1. **Hero Section**: Purple background (adapts to dark mode) with title,
description, and Arcade demo embed
2. **Navigation Grid**: 6 cards with custom SVG icons:
- Platform → `/platform/`
- Connectors → `/integrations/`
- Release Notes → `/release_notes/`
- AI Agents → `/ai-agents/`
- Developers → `/platform/api-documentation`
- Community and Support → `/platform/community/getting-support`
3. Fully responsive design (3 columns → 2 columns → 1 column)
4. Fast hover transitions (0.2s ease-out)
5. Empty page title to use site-level title (avoids "Airbyte
Documentation | Airbyte Docs" duplication)
**Content Migration:**
- Moved "Why Airbyte?" section with badges from home page to
`/docs/platform/readme.md`
## Review guide
**Critical files (routing change):**
1. `docusaurus/docusaurus.config.js` - Verify the docs plugin disable
and pages plugin enable
2. `docusaurus/src/pages/index.js` - New home page React component,
check all navigation links
**Styling:**
3. `docusaurus/src/pages/index.module.css` - Check CSS variables are
defined:
- `--color-grey-40`
- `--color-blue-30`
- `--ifm-color-primary-lightest`
- Responsive breakpoints at 996px and 640px
**Content:**
4. `docs/platform/readme.md` - Verify "Why Airbyte?" section placement
makes sense here
5. Deleted files (`docs/home/readme.md`, `sidebar.js`) - Confirm no
other references exist
**Testing checklist:**
- [x] Navigate to `/` and verify new home page renders
- [x] Test all 6 navigation card links
- [x] Toggle dark/light mode
- [x] Test responsive design at tablet (996px) and mobile (640px)
breakpoints
- [x] Verify Arcade embed loads correctly
- [x] Check `/platform/` page has "Why Airbyte?" section
- [x] Verify page title doesn't show duplicate "Airbyte Documentation"
**Accessibility concerns:**
- SVG icons lack aria-labels - should be addressed in follow-up
## User Impact
Users will see a modernized home page with:
- Prominent hero section with purple Airbyte branding
- Clear navigation cards with icons and descriptions
- Improved mobile experience
- Faster hover interactions
**Potential negative impacts:**
- "Why Airbyte?" content moved from home to platform page - users
expecting it on home page won't find it there
- Old bookmarks to `/docs/home` may break (though likely redirected by
Docusaurus)
- Page title behavior changed (empty title uses site title)
## Can this PR be safely reverted and rolled back?
- [x] YES 💚
This is a pure UI change with no backend or data modifications. The old
markdown file can be restored from git history. All navigation links
point to existing routes.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: ian.alton@airbyte.io <ian.alton@airbyte.io>
## What
Adds automation for syncing evergreen documentation to versioned docs,
and applies it to update version-2.0 docs. Follow-up to #68098 which
reorganized breaking changes documentation.
Requested by @aaronsteers in
https://app.devin.ai/sessions/644caae698024ce99ebb5a34609b785c.
## How
**New Poe Task** (`poe-tasks/repo-root-tasks.toml`):
- Created `poe docs-update-latest-evergreen` task
- Reads latest version from `platform_versions.json` (currently 2.0)
- For each specified directory (`connector-development/`,
`contributing-to-airbyte/`):
- Removes old versioned directory content with `rm -rf`
- Copies fresh content from main docs
- This ensures versioned docs are fully replaced (no stale files remain)
**Version-2.0 Docs Updates**:
- Applied task to sync latest connector development and contribution
guides
- This brought in changes from #68098 including the new
`connector-breaking-changes.md`
- Removed obsolete files that no longer exist in main docs:
- `contributing-to-airbyte/change-cdk-connector.md` (replaced by
connector-breaking-changes.md)
- `contributing-to-airbyte/submit-new-connector.md` (moved to
connector-development/)
## Review Guide
**🔴 CRITICAL - Destructive Operation:**
1. `poe-tasks/repo-root-tasks.toml` (lines 39-57)
- **Review the `rm -rf "$DEST"` approach**: This completely removes
directory contents before copying
- **Verify directory scope is appropriate**: Only
`connector-development/` and `contributing-to-airbyte/` are affected
- **Question: Are these directories truly 100% evergreen?** No
version-specific content should exist in these paths
**🟡 IMPORTANT - File Organization:**
2. Deleted files:
- `contributing-to-airbyte/change-cdk-connector.md` - Verify no incoming
links are broken
- `contributing-to-airbyte/submit-new-connector.md` - Now in
`connector-development/`
3. Link updates:
- `connector-development/README.md` - Updated submit-new-connector link
- `contributing-to-airbyte/README.md` - Updated connector guide
references
- `contributing-to-airbyte/developing-locally.md` - Updated
submit-new-connector link
- Verify all relative paths are correct from new locations
**🟢 MINOR - Documentation Content:**
4. `connector-development/connector-breaking-changes.md` - New
comprehensive guide (from #68098)
5. `connector-development/local-connector-development.md` - Added
breaking changes reference
## User Impact
**Positive:**
- Version-2.0 docs now include updated breaking changes guidance from
#68098
- Automated task reduces manual effort for future doc syncs
- Contributors viewing versioned docs get accurate connector development
information
**Potential Issues:**
- Task must be run manually after main docs updates (no automated
trigger)
- If any version-specific content exists in synced directories, it will
be incorrectly overwritten
- The `rm -rf` approach is aggressive - any mistake in directory paths
could be destructive
## Can this PR be safely reverted and rolled back?
- [x] YES 💚
Pure documentation changes. Reverting removes the Poe task and reverts
versioned docs to previous state. Main (latest) docs are unaffected.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
## What
Generates version 2.0 of the Airbyte platform documentation using
Docusaurus's built-in versioning system. This creates a frozen snapshot
of the current documentation that users can reference.
Requested by ian.alton@airbyte.io via [Slack
thread](https://airbytehq-team.slack.com/archives/D08FX8EC9L0/p1760490197805979?thread_ts=1760490197.805979).
Link to Devin run:
https://app.devin.ai/sessions/689693593bac44f4903f476aa17b872e
## How
- Ran `pnpm run docusaurus docs:version:platform 2.0` in the docusaurus
directory
- This automatically:
- Created `platform_versioned_docs/version-2.0/` containing a snapshot
of all current platform docs
- Created `platform_versioned_sidebars/version-2.0-sidebars.json` with
the sidebar navigation structure
- Updated `platform_versions.json` to add "2.0" to the version list
- Ran prettier to format the JSON files
- Verified the documentation builds successfully locally (build
completed in ~3 minutes with only pre-existing broken anchor warnings)
## Review guide
1. **Verify timing**: Confirm this is the correct time to release
version 2.0 of the documentation
2. **Version order**: Check `docusaurus/platform_versions.json` - verify
"2.0" is first in the array (newest version first)
3. **Build verification**: Ensure CI/Vercel builds pass without errors
4. **Spot check**: Optionally review 2-3 files in
`docusaurus/platform_versioned_docs/version-2.0/` to ensure content
looks reasonable
Note: This is a standard Docusaurus versioning operation that creates a
frozen snapshot of the current "next" documentation. The generated files
are extensive (500+ files) but follow Docusaurus conventions.
## User Impact
Users will see version 2.0 available in the version dropdown on
docs.airbyte.com. This provides a stable reference point for platform
documentation at this point in time. Existing versions (1.6, 1.7, 1.8)
remain unchanged.
## Can this PR be safely reverted and rolled back?
- [x] YES 💚
This is an additive change that doesn't modify existing versioned docs.
Reverting would simply remove version 2.0 from the version list and
delete the associated documentation files.
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: ian.alton@airbyte.io <ian.alton@airbyte.io>
## What
<!--
* Describe what the change is solving. Link all GitHub issues related to
this change.
-->
Release notes for Airbyte 2.0.
Also:
- Added new terminology to linting allowlist for Vale.
- Added a React component so we can embed YouTube videos.
## How
<!--
* Describe how code changes achieve the solution.
-->
## Review guide
<!--
1. `x.py`
2. `y.py`
-->
## User Impact
<!--
* What is the end result perceived by the user?
* If there are negative side effects, please list them.
-->
## Can this PR be safely reverted and rolled back?
<!--
* If unsure, leave it blank.
-->
- [x] YES 💚
- [ ] NO ❌
## What
The OpenTelemetry docs were unclear on how to actually configure the
Collector and Airbyte to connect, as well as necessary prereqs to do so.
This PR just updates to make those a little clearer.
## How
Docs updates.
## Review guide
Validate docs makes sense.
## User Impact
n/a
## Can this PR be safely reverted and rolled back?
<!--
* If unsure, leave it blank.
-->
- [x] YES 💚
- [ ] NO ❌
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
<!--
* Describe what the change is solving. Link all GitHub issues related to
this change.
-->
This PR adds support for migration guides on enterprise connectors.
<img width="1920" height="883" alt="image"
src="https://github.com/user-attachments/assets/8a94d7a7-e390-4460-900c-bfaf000e6f0b"
/>
## How
<!--
* Describe how code changes achieve the solution.
-->
Updated filtering logic to support top-level `id` as well as nested
`link.id`.
The existing filtering logic for enterprise connectors in the sidebar
did not expect nested migration guides. The reason is because the
getFilenamesInDir() function returns two different object structures.
Simple doc (no migration file): { type: "doc", id: "...", label: "..." }
- has id at top level
Category with migration doc: { type: "category", label: "...", link: {
id: "..." }, items: [...] } - has id nested in link.id
@darynaishchenko discovered during work on
https://github.com/airbytehq/airbyte/pull/67214 that all builds failed
when a migration guide was added to an enterprise connector.
## Review guide
1. Review the logic in the sidebar filtering code.
2. There is currently no migration guide in master to test this on, but
I did test this fix with Darnya's PR and it built correctly with the
updated code. You can simulate a migration guide by adding a dummy
`<connector_filename>-migrations.md` doc for an enterprise connector. At
build time it should nest appropriately under its parent object.
## User Impact
<!--
* What is the end result perceived by the user?
* If there are negative side effects, please list them.
-->
Enterprise customers can have migration guides too.
## Can this PR be safely reverted and rolled back?
<!--
* If unsure, leave it blank.
-->
- [x] YES 💚
- [ ] NO ❌
## What
Based on some customer feedback that our setup guides were a bit
difficult to follow and they just wanted a one page step-by-step.
- Adds a straight shooting one-page guide for folks embedding us into an
existing application
- Moves existing getting started guides that showcased demo applications
into a "Tutorials" area
This does depend on https://github.com/airbytehq/sonar/pull/1049 being
merged, which moves the Applications Token endpoint to the public Sonar
API (another request from that customer!)
