102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# Documentation and Docusaurus
|
|
|
|
We use [Docusaurus](https://docusaurus.io) to build Airbyte's
|
|
[documentation site](https://docs.airbyte.io) 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).
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](https://github.com/airbytehq/airbyte/blob/master/docusaurus/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.
|
|
- Run `pnpm prettier . -w`.
|
|
- 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.
|
|
|
|
> [!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](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects)
|
|
|
|
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](https://github.com/airbytehq/airbyte/blob/master/docusaurus/docusaurus.config.js#L22)
|
|
|
|
You will see a commented section the reads something like this
|
|
|
|
```js
|
|
// {
|
|
// from: '/some-lame-path',
|
|
// to: '/a-much-cooler-uri',
|
|
// },
|
|
```
|
|
|
|
Copy this section, replace the values, and [test it locally](locally_testing_docusaurus.md) 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](https://github.com/airbytehq/airbyte/tree/master/docs). 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.
|