Documentation and Docusaurus

We use docusaurus for consistent process, in Airbyte no website is generated. Functionally this is a very fancy linter

Running the build process will check for broken links, please read the output and address any broken links that you are able to do.

Installation

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

brew install yarn

cd docusaurus
yarn install
yarn build

At this point you will see any broken links that docusaurus was able to find.

Developing Locally

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

Making Changes

All the content for docs.airbute.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!

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

Plugin Client Redirects

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

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

We use Github Pages for hosting this docs website, and Docusaurus as the docs framework. 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.