Static site generators

Aerobatic is a perfect hosting complement to static site generators such as Jekyll, Hugo, Hexo, Gatsby and others. Simply configure aerobatic-cli to deploy the directory where the generator emits the built site (_site, public, dist, etc.). Aerobatic works with any tool that generates static HTML, but we provide some specific guidance for the following popular generators:

Specifying deploy directory

There are two ways to configure the deploy directory:

  • Add a deploy section to your aerobatic.yml with a directory prop:

      directory: _site

    With this approach you just run aero deploy to deploy your site.

    Or, pass a command line option:

$ aero deploy --directory \_site # You can also use shorthand -d

Full docs on the deploy command

Configuring the site url {#configuring-site-url}

In general we suggest using relative URLs in your template files since the browser will automatically resolve them to the current host and protocol. For example:

<!-- Prefer this: -->
<a href="/about/contact">Contact Us</a>
<!-- Over this: -->
<a href="">Contact Us</a>

That way the same markup will function identically no matter where what the base host is, i.e. http://localhost:4000,, or

However, most static site generators have a url or baseURL config setting that is used to build an absolute URL. You could hardcode this value to your production URL, but then it won't automatically adjust when you push the version from one stage to another, i.e. to If you are going to be taking advantage of deploy stages, we recommend that you specify the reserved value https://!!baseurl!! which Aerobatic substitutes at render time with the actual requested site url. We offer ways to configure this for specific generators below.

Generator configurations

Here some configuration tips for some of the popular static site generators. Even if your generator isn't listed, it's likely that it offers very similar functionality. These tips are relevant both when deploying to Aerobatic locally or from a continuous integration build.

Jekyll {#jekyll-generator}

Here's how to generate a new Jekyll site from scratch and deploy it to Aerobatic:

$ jekyll new my-jekyll-site
$ cd my-jekyll-site
$ aero create # create the Aerobatic site
$ echo "url: https://!!baseurl!!" > _aerobatic.config.yml # override site.url for Aerobatic
$ jekyll build --config _config.yml,_aerobatic.config.yml # generate the output
$ aero deploy --directory _site # deploy output to Aerobatic

Rather than passing the --directory option every time, you can alternatively specify it in the aerobatic.yml file.

directory: \_site

Putting this all together for a CI build, your script might look like the following:

$ bundle install # Re-run on every build in a CI enviroment
$ jekyll build --config _config.yml,_config.aerobatic.yml
$ aero deploy --directory _site

We recommend that you use the pretty permalink style for extension-less URLs. This avoids incurring a redirect when hosted on Aerobatic.

Additional reading

Hugo {#hugo-generator}

Here's how you to create a new Hugo site from scratch and deploy to Aerobatic:

$ hugo new site my-new-hugo-site
$ cd my-new-hugo-site
$ mkdir -p themes
$ (cd themes; git clone # clone a theme
$ aero create" "create the Aerobatic site
$ hugo --baseURL https://!!baseurl!! --theme liquorice # build the site overriding baseURL
$ aero deploy -d public # deploy output to Aerobatic

The spf13/hugoThemes repo has an extensive collection of git sub-modules. Click on anyone of them to get the URL of an individual theme.

In the rendered page response, the https://!!baseurl!! will be replaced with the actual site url.

Installing Hugo on a build server image

If you need to install hugo in a CI script, here's the commands for doing so (assuming an Ubuntu based build image). You can obviously specify whatever version of hugo you like.

apt-get update -y && apt-get install wget
dpkg -i hugo*.deb

If your CI service supports custom Docker images, we've provided the aerobatic/hugo image which has hugo, aerobatic-cli, and other supporting software all set to go. See this blog post to learn how to build and deploy your Hugo sites with Bitbucket Pipelines. This additional blog post shows how to build and deploy your Hugo site with GitHub and CircleCI.

Hexo {#hexo-generator}

Here's how to create a new Hexo site and deploy it to Aerobatic:

$ hexo init new-hexo-site
$ cd new-hexo-site
$ npm install
$ aero create # create the Aerobatic site
$ echo "url: https://!!baseurl!!" > _aerobatic.config.yml" # override site.url for Aerobatic
$ hexo generate --config _config.yml,_aerobatic.config.yml # generate the output
$ aero deploy -d public # deploy output to Aerobatic

Gatsby {#gatsby-generator}

Here's how to generate a new Gatsby site from scratch and deploy it to Aerobatic:

$ gatsby new gatsby-project
$ cd gatsby-project
$ aero create --name my-gatsby-project # create the Aerobatic site
$ gatsby build # build the gatsby site
$ aero deploy --directory public # deploy build output to Aerobatic

React {#react-generator}

Here's how to create a new React app from scratch using the excellent create-react-app tool and deploy it to Aerobatic:

$ create-react-app my-react-app
$ cd my-react-app
$ aero create # create the Aerobatic site
$ yarn build # generate the production optimized build
$ aero deploy --directory build # deploy output to Aerobatic

Hosting your static React front-end on Aerobatic paired with a serverless backend running on service like AWS API Gateway is a great decoupled front end / backend setup. In fact that's exactly how our Dashboard works.

Yeoman {#yeoman-generator}

Here's how to create a new AngularJS app with Yeoman and deploy it to Aerobatic:

$ mkdir my-angular-app
$ cd my-angular-app
$ yo angular # scaffold the angular app
$ aero create # create the Aerobatic site
$ gulp build # build the production output
$ aero deploy --directory dist # deploy output to Aerobatic

Of course there are many other Yeoman generators that emit a static site which can be used in the same basic manner.

Plain Html {#html-generator}

Ok, plain html isn't really a generator at all. No build step necessary, just run aero deploy right from the root of your project.

$ mkdir plain-html
$ cd plain-html
$ echo "<html>Hello Aerobatic!</html>" > index.html
$ aero create
$ aero deploy