Documentation and Docusaurus

We use Docusaurus to build Airbyte's documentation site from documentation source files in Markdown, and lint the source files. We host the resulting docs site on Vercel. It deploys automatically when any changes get merged to master.

Installation

For consistency across other Airbyte projects we use pnpm (A Javascript based software package manager).

brew install pnpm

cd docusaurus
pnpm install
pnpm build

pnpm build will build Docusaurus site in docusaurus/build directory.

Developing Locally

If you want to make changes to the documentation, you can run docusaurus locally in a way that would listen to any source docs changes and live-reload them:

pnpm start # any changes will automatically be reflected in your browser!

All the content for docs.airbyte.com lives in the /docs directory in this repo. All files are markdown. Make changes or add new files, and you should see them in your browser!

Changing Navigation Structure

If you have created any new files, be sure to add them manually to the table of contents found here in sidebars.js

Contributing

We welcome documentation updates! If you'd like to contribute a change, please make sure to:

• Run pnpm build and check that all build steps are successful.
• Push your changes into a pull request, and follow the PR template instructions.

When you make a pull request, Vercel will automatically build a test instance of the full docs site and link it in the pull request for review.

Checking for broken links

Airbyte's docs site checks links with Docusaurus at build time, and with an additional GitHub action periodically:

• Running the build process will check for broken links, please read the output and address any broken links that you are able to do.
• This GitHub Action checks all links on Airbyte production docs site, and tells us if any of them are broken.

[!NOTE] Docusaurus links checker only checks relative links, and assumes that absolute links are fine. For that reason, if you're linking to another Airbyte documentation page, make it a relative link. I.e. [link](/connector-development/overview.md) instead of [link](https://docs.airbyte.com/connector-development/). That way, if your link breaks in the future due to a navigation restructure, it will be caught with pnpm build.

Docusaurus Plugins We Use

Plugin Client Redirects

A silly name, but a useful plugin that adds redirect functionality to docusaurus Official documentation here

If you're proposing to move an existing documentation file or change its name, please setup a redirect rule.

You will need to edit this docusaurus file

You will see a commented section the reads something like this

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

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

Note: Your path *needs a leading slash / to work

Deploying Docs

Airbyte docs live on Vercel. Any change to the /docs directory you make is deployed when you merge to your PR to the master branch automagically!

The source code for the docs lives in the airbyte monorepo's docs/ directory. Any changes to the /docs directory will be tested automatically in your PR. Be sure that you wait for the tests to pass before merging! If there are CI problems publishing your docs, you can run tools/bin/deploy_docusaurus locally - this is the publish script that CI runs.