We use docusaurus to power docs.getdbt.com.

Versioning with branches

We currently version our docs by using two long-lived branches in this repo:

• current: This branch is what is reflected at at docs.getdbt.com
• next: This branch represent the next release of dbt, and is deployed next.docs.getdbt.com

Contributing

We welcome contributions from community members to this repo:

• Fixes: If you notice an error (there are likely many), use the Edit this page button at the bottom of each page to suggest a change. We recommend you contribute small changes directly from the GitHub interface.
• New documentation: If you contributed code in dbt-core, we encourage you to also write the docs here!
• Refactors: At this time, we are unable to support community members who wish to re-write sections of docs.getdbt.com. We hope to change this in the future!

Running the Docs site locally

You can click a link available in a netlify bot PR comment to see and review your changes rendered on a staging server. You are also able to see and review your proposed modifications locally on your computer. Our setup instructions use homebrew:

0. If applicable, install Xcode Command Line Tools; you'll likely need an AppleID for this. You will also need homebrew.
1. Install node: brew install node
2. Clone this repo: git clone [email protected]:fishtown-analytics/docs.getdbt.com.git
3. cd into the repo: cd docs.getdbt.com
4. cd into the website subdirectory: cd website
5. Install the required node packages: npm install
6. Build the website: npm start
7. Before pushing your changes to a branch, check that all links work by using the make build script.

Advisory:

• Currently an npm install produces a number of dependency warnings, in particular several claiming that docusaurus/core is missing. Rest assured, this message is a red herring. As of writing this, no 2.0.0 package exists, so you won't have much luck trying to install it. Feel free to ignore those warnings.
• If you run into an fatal error: 'vips/vips8' file not found error when you run npm install, you may need to run brew install vips. Warning: this one will take a while -- go ahead and grab some coffee!

You can also check out this Loom video that I recorded for co-workers — it covers setting up docs.getdbt.com locally, and adding a page with links and images. Heads up — this was very much something I did on the fly, so is not super polished!

Custom components

Check out docs.getdbt.com/styles for examples of different components that can be used in these docs.

You can also use components directly from the docusaurus library.