Where to Discuss?

Local Group

Preface

Goal: Deploy SSG using Travis.

After finishing steps in previous article. Now it is time to push to go to the configuration detail.

Travis use .travis.yaml as a configuration. YAML engineer folks should be feels like home. Each SSG have their own different configuration.

Reading

Follow the official documentation:


3: Basic: Language

Since each SSG might have different platform, most .travis.yml utilize language environment definition.

1: Jekyll

language: ruby
rvm:
  - 2.6.3

2: Pelican

language: python

python:
  - 3.5

3: Hugo

Hugo use static binary executable. Thus, no language environment required.

4: Hexo

language: node_js
node_js:
  - 8

5: Eleventy

language: node_js
node_js:
  - 8

4: Script: Install and Build

Commonly, there are two kind of script:

  • before_script: install required SSG

  • script: build site

1: Jekyll

before_script: bundle install
script: bundle exec jekyll build

2: Pelican

before_script:
  - pip install --upgrade pip
  - pip install -r requirements.txt

script:
  - make html

Which the requirement.txt in my case is:

Jinja2   ~= 2.10.1
pelican  ~= 4.2.0
Markdown ~= 3.1.1

3: Hugo

before_script:
  - curl -LO https://github.com/gohugoio/hugo/releases/download/v0.55.4/hugo_0.55.4_Linux-64bit.deb
  - sudo dpkg -i hugo_0.55.4_Linux-64bit.deb

script:
  - hugo

4: Hexo

script:
  - hexo generate # generate static files

5: Eleventy

before_script:
  - npm install @11ty/eleventy -g

script: eleventy --pathprefix="/travis-11ty/"

5: Deploy

Github using gh-pages branch as a place for generated result. Travis manage this easily using pages provider. No need any complex git worktree.

The configuration is short, but you have to setup $GITHUB_TOKEN in environment, to enable Travis writing to gh-pages. For example this eleventy site:

deploy:
  local-dir: dist
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

The only different between SSG is local-dir.

1: Jekyll

deploy:
  local-dir: _site

2: Pelican

deploy:
  local-dir: output

3: Hugo

deploy:
  local-dir: public

4: Hexo

deploy:
  local-dir: public

5: Eleventy

Eleventy is very flexible, you can easily change output directory. The default is _site, but in my case, change it to dist.

deploy:
  local-dir: dist

6: Complete YAML.

Now we can see them all running.

Travis: My Repository

As a summary, here is the complete configuration fo each SSG.

1: Jekyll

language: ruby
rvm:
  - 2.6.3

before_script: bundle install
script: bundle exec jekyll build

deploy:
  local-dir: _site
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

2: Pelican

sudo: false

language: python

python:
  - 3.5

before_script:
  - pip install --upgrade pip
  - pip install -r requirements.txt

script:
  - make html

deploy:
  local-dir: output
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

3: Hugo

before_script:
  - curl -LO https://github.com/gohugoio/hugo/releases/download/v0.55.4/hugo_0.55.4_Linux-64bit.deb
  - sudo dpkg -i hugo_0.55.4_Linux-64bit.deb

script:
  - hugo

deploy:
  local-dir: public
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

4: Hexo

From Hexo official site:

sudo: false

language: node_js
node_js:
  - 8

cache: npm
branches:
  only:
    - master # build master branch only
script:
  - hexo generate # generate static files

deploy:
  local-dir: public
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

5: Eleventy

language: node_js
node_js:
  - 8

before_script:
  - npm install @11ty/eleventy -g

script: eleventy --pathprefix="/travis-11ty/"

deploy:
  local-dir: dist
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

7: Adjustment

All SSG works well in my case, just need a few adjustment.

1: Jekyll

language: ruby
rvm:
  - 2.6.3

2: Pelican

language: python

python:
  - 3.5

3: Hugo

Hugo use static binary executable. Thus, no language environment required.

4: Hexo

language: node_js
node_js:
  - 8

5: Eleventy

language: node_js
node_js:
  - 8

7: URL Adjustment

You only need this adjustment if you use github pages.

1: Jekyll

Since the repository use github pages, we should set the _config.yml as below example:

# the subpath of your site, e.g. /blog
baseurl: "/travis-jekyll" 

2: Pelican

This is the easiest one. No adjustment required.

3: Hugo

Since the repository use github pages, we should set the config.toml as below example:

# The subpath of your site, e.g. /blog
baseURL      = "/travis-hugo"

4: Hexo

Since the repository use github pages, we should set the root as below example:

This travis example has _config.yml as below

root          : /travis-hexo/

And has _config_local.yml as below

root          : /

To run locally you can override use this command.

hexo server -p 5000 --debug --config _config.yml,_config_local.yml

If you use link in landing page, it should also altered manually, because Hexo did not come with absolute path.

For example this source/index.html, we should add /travis-hexo/ as below example below:

  <p>
    <a href="/travis-hexo/archives/" 
       class="button is-dark has-margin-bottom-5"
      >Articles Sorted by Month</a>
    <a href="/travis-hexo/tags.html" 
       class="button is-primary has-margin-bottom-5"
      >Articles Sorted by Tag</a>
  </p>

Another needed adjustment is in EJS part. If you accidentaly code using each as below example:

  if (page.categories) {
    page.categories.each(function(item){
      terms.push(item.name);
    })
  }

  if (page.tags) {
    page.tags.each(function(item){
      terms.push(item.name);
    })
  }

You should change it to forEach.

  if (page.categories) {
    page.categories.forEach(function(item){
      terms.push(item.name);
    })
  }

  if (page.tags) {
    page.tags.forEach(function(item){
      terms.push(item.name);
    })
  }

5: Eleventy

Since the repository use github pages, we should set the .eleventy.js as below example:

const config = {
    // URL related
    pathPrefix: "/travis-11ty/",
    
    dir: {
      ...
      output: "dist",
    }
}

So that we ca nsynchronize with --pathprefix="/travis-11ty/" in command above.


8: Miscellanous Adjustment

The only SSG that need adjustment is Jekyll.

1: Jekyll

The Gemfile. Comment specific gem for windows platform as needed, such as tzinfo and wdm.

5: Eleventy

You might seen in official Eleventy something like this:

before_script: npm install
script: npm run test

If Travis complain about test, you can make dummy test command.

  "scripts": {
    "build": "eleventy",
    "watch": "eleventy --watch",
    "debug": "DEBUG=* eleventy",
    "test": "echo \"No Error: test specified\""
  },

But this is not necessary, since my example script is different, as below:

before_script: npm install @11ty/eleventy -g
script: eleventy --pathprefix="/travis-11ty/"

What is Next ?

Consider continue reading [ CI/CD - CircleCI - Part One ]. A different CI/CD that you can compare with Travis.