Skip to main content

Updating Documentation

We welcome contributions to the Airbyte documentation!

Our docs are written in Markdown following the Google developer documentation style guide and the files are stored in our Github repository. The docs are published at using Docusaurus and GitHub Pages.

Finding good first issues

The Docs team maintains a list of #good-first-issues for new contributors.

  • If you're new to technical writing, start with the smaller issues (fixing typos, broken links, spelling and grammar, and so on). You can edit the files directly on GitHub.
  • If you're an experienced technical writer or a developer interested in technical writing, comment on an issue that interests you to discuss it with the Docs team. Once we decide on the approach and the tasks involved, edit the files and open a Pull Request for the Docs team to review.

Contributing to Airbyte docs

Before contributing to Airbyte docs, read the Airbyte Community


If you're new to GitHub and Markdown, complete the First Contributions tutorial and learn Markdown basics before contributing to Airbyte documentation.

You can contribute to Airbyte docs in two ways:

Editing directly on GitHub

To make minor changes (example: fixing typos) or edit a single file, you can edit the file directly on GitHub:

  1. Click Edit this page at the bottom of any published document on You'll be taken to the GitHub editor.
  2. Edit the file directly on GitHub and open a Pull Request.

Editing on your local machine

To make complex changes or edit multiple files, edit the files on your local machine:

  1. Fork the Airbyte repository.

  2. Clone the fork on your local machine:

    git clone [email protected]:{YOUR_USERNAME}/airbyte.git
    cd airbyte


    git clone{YOUR_USERNAME}/airbyte.git
    cd airbyte

    While cloning on Windows, you might encounter errors about long filenames. Refer to the instructions here to correct it.

  3. Test changes locally:

    To install the docs locally, run the following commands in your terminal:

    cd docusaurus
    yarn install

    To see changes as you make them, run:

    yarn start

    Then navigate to http://localhost:3000/. Whenever you make and save changes, you will see them reflected in the server. You can stop the running server in OSX/Linux by pressing Ctrl-C in the terminal.

    You can also build the docs locally and see the resulting changes. This is useful if you introduce changes that need to be run at build-time (e.g. adding a docs plug-in). To do so, run:

    yarn build
    yarn serve

    Then navigate to http://localhost:3000/ to see your changes. You can stop the running server in OSX/Linux by pressing Ctrl-C in the terminal.

  1. Follow the GitHub workflow to edit the files and create a pull request.


    Before we accept any contributions, you'll need to sign the Contributor License Agreement (CLA). By signing a CLA, we can ensure that the community is free and confident in its ability to use your contributions. You will be prompted to sign the CLA while opening a pull request.

  2. Assign airbytehq/docs as a Reviewer for your pull request.

Additional guidelines

  • If you're updating a connector doc, follow the Connector documentation template
  • If you're adding a new file, update the sidebars.js file
  • If you're adding a README to a code module, make sure the README has the following components:
    • A brief description of the module
    • Development pre-requisites (like which language or binaries are required for development)
    • How to install dependencies
    • How to build and run the code locally & via Docker
    • Any other information needed for local iteration

Advanced tasks

Adding a redirect

To add a redirect, open the docusaurus.config.js file and locate the following commented section:

//                        {
// from: '/some-lame-path',
// to: '/a-much-cooler-uri',
// },

Copy this section, replace the values, and test the changes locally by going to the path you created a redirect for and verify that the address changes to the new one.


Your path needs a leading slash / to work

Deploying and reverting the documentation site


Only the Airbyte team and maintainers have permissions to deploy the documentation site.

Automated documentation site deployment

When docs/ folder gets changed in master branch of the repository, Deploy Github workflow steps in, builds and deploys the documentation site. This process is automatic, takes five to ten minutes, and needs no human intervention.

Manual documentation site deployment


Manual deployment is reserved for emergency cases. Please, bear in mind that automatic deployment is triggered by changes to docs/ folder, so it needs to be disabled to avoid interference with manual deployment.

You'll need a GitHub SSH key to deploy the documentation site using the deployment tool.

To deploy the documentation site, run:

cd airbyte
# or cd airbyte-cloud
git checkout master
git pull

To revert/rollback doc changes, run:

cd airbyte
git checkout <OLDER_BRANCH>