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 docs.airbyte.com 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

tip

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 docs.airbyte.com. 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 git@github.com:{YOUR_USERNAME}/airbyte.git
    cd airbyte

    Or

    git clone https://github.com/{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.

    note

    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.

note

Your path needs a leading slash / to work

Deploying and reverting the documentation site​

note

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 docs.airbyte.com 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​

note

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
./tools/bin/deploy_docusaurus

To revert/rollback doc changes, run:

cd airbyte
git checkout <OLDER_BRANCH>
./tools/bin/deploy_docusaurus
Was this page helpful?