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.
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
$ touch docs/_include/.nojekyll
$ 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
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
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,
firstname.lastname@example.org does not work for projects without a package.json
file. This is why this guide recommends using
3.0.0. Read more in this
npm install -g email@example.com
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
All that is left to do, is run the
$ gh-pages -d site Published