Continuous Integration (CI) for Gitbook using Gitlab and Gulp

Gitbook is a static site generator, that converts a collection of Markdown files into an HTML Site. Alternatively, it can also convert the markdown files into a PDF or ebook.
If you are not writing a book, it is also a great tool to create a quick documentation for a project you are working on.

Initial set up

We will need gitbook. Gitbook does not automatically generate a SUMMARY.md file, however, there is an existing gitbook-summary tool to take care of that.

Gulp will be our task runner.

I will deploy to my server via FTP. Since you are only serving HTML Files, there is usually no need for server restart etc.
To integrate it into Gulp I will be using vinyl-ftp.

npm init
# Install Gitbook Tools
npm install --save-dev gitbook gitbook-cli gitbook-summary 

# Install Gulp with Tools
npm install --save-dev gulp gulp-gitbook

# Install FTP with needed Gulp Tools
npm install --save-dev vinyl-ftp gulp-util

Gulp

Create a file called gulpfile.js and define your gulp tasks.

You should test especially the “deploy” task locally if everything is working correctly.

let gulp = require("gulp");
let gitbook = require("gulp-gitbook");
let ftp = require("vinyl-ftp");
let gutil = require("gulp-util");
var summary = require("gitbook-summary/lib/summary");

gulp.task("default", ["build"]);

//Generates the Summary.md file
gulp.task('summary', ()=> {
    let options = {
        root: "."
    }
    return summary(options);
});

//Generates the Website
gulp.task('build', ["summary"], (cb) => {
  gitbook('.', cb);
});


//Deploys the output onto your server
gulp.task('deploy', ["build"], () => {
    var conn = ftp.create( {
        host:     '<url>',
        user:     '<username>',
        password: '<password>',
        parallel: 10,
        log:      gutil.log
    } );
 
    var globs = [
        '_book/**'
    ];

    return gulp.src( globs, { buffer: false } )
        .pipe( conn.newer( '.' ) ) // only upload newer files 
        .pipe( conn.dest( '<server directory>/' ) ); // Depending on your server you may have to prefix something like /home/www/
});

Gitlab CI Integration

You need to create a YAML File called .gitlab-ci.yml. Gitlab will recognize the file and run the commands in it.

image: node:latest

cache:
  paths:
   - node_modules/

before_script:
  - npm install
  - npm install -g gulp

deploy:
  only:
   - master
  script:
   - gulp deploy

That’s it. If you push something into the master branch, it will automatically run the commands in the yaml file and deploy your static website to your server.
When the build completes, you will receive an email, telling you if everything went as planned.