Deployment

Doctave builds a static site bundle into the site directory which is fully self contained. You can take the output of doctave build --release and deploy it in any way you see fit.

Below is a walkthrough on how to publish your docs on Github Pages. We will be adding more tutorials for other hosting options over time.

Github Pages

This guide assumes you have:

• Hosted your repository on Github
• Enabled Github Pages in your repository's settings

Disable Jekyll builds

First, you need to tell Github not to use Jekyll to build your site. You do this by including a .nojekyll file in the root of site.

In Doctave, you do this by adding the file under docs/_include.

On Mac/Linux:

$ touch docs/_include/.nojekyll

On Windows:

$ echo.> docs\_include\.nojekyll

Custom domain name (optional)

If you have a custom domain, Github requires you to create a CNAME file that describes your domain in the root of your site. Just like with the .nojekyll file, you need to place this under docs/_include.

Install gh-pages

There are a few ways to push your site to Github. One way, which we will follow here, is to use a gh-pages branch to publish the site. This means you build the site into a separate branch, commit only the site folder in that branch, not your other source code, and push it to Github.

Luckily, there is a handy command line tool, gh-pages that takes care of all of that for you. All you need to do, is run a single command, and your site will be published.

Note: At the time of writing, gh-pages@3.1.0 does not work for projects without a package.json file. This is why this guide recommends using 3.0.0. Read more in this issue.

npm install -g gh-pages@3.0.0

Build your site

Next, build your site in release mode. This strips away some development-only dependencies:

$ doctave build --release

Your site should now be ready in the site directory.

Deploy

All that is left to do, is run the gh-pages command:

$ gh-pages -d site
Published