Publishing Documentation

A core part of docs-as-code is that you automatically update your documentation as part of CI/CD. Doctave is designed to work perfectly in such an environment.

Each Doctave project follows a Git branch and will get published when a new upload is made in that branch.

Upload tokens

Your Doctave project is allocated an upload token. You use this token when publishing your documentation to tell Doctave which project the content belongs to.

Your project's upload token is found under the project settings page:

1. Go to the project list in the Doctave dashboard
2. Click on "Configure" for your project
3. Click "Settings" in the left navigation

You can find the upload token at the top of the project settings page.

Upload script

Doctave provides a convenience script that packages up your documentation and uploads it to our servers. All files and folders that are in the same directory as your project configuration file will be uploaded.

Doctave never accesses the rest of your source code and we do not require access to your repository. You push your docs to us.

To invoke the script, invoke it like so:

# Export your project's unique upload token
export DOCTAVE_UPLOAD_TOKEN=<your project's upload token>

# Make sure you're in the same directory as the doctave.yaml file
cd path/to/my/docs

# Publish!
curl -L http://dashboard.doctave.com/doctave-upload.sh | bash -s -- .

The script itself is only ~150 lines long. It runs a couple git commands in order to check which branch and commit the changes belong to, packages your docs, and sends them over.

When to publish?

This is another case where Doctave is different from many other documentation platforms: we encourage you to publish often.

Doctave will only show your users builds that happen in the branch you have selected to publish. If you upload a set of docs from a different branch, Doctave will create a preview environment for that build, which is only visible to your team members.

This means you get automatic previews for all your uploads. You are able to show off your work and easily gather feedback before making your changes public to your readers.

We recommend you upload your docs to Doctave on every change through your CI/CD pipeline. For more information, read our CI/CD how-to.

Next step

➤ Finally, let's talk about how collaboration with your team happens in practice!