grunt-bitbucket-pages

grunt-bitbucket-pages

Publish to BitBucket Pages with Grunt.

Note: This grunt task is a work in progress and does not yet have a stable api. If stability is important to you please wait for the 1.0.0 release.

This documentation assumes you are familiar with the BitBucket Pages feature.

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-bitbucket-pages --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-bitbucket-pages');

The "bitbucket-pages" task

Overview

In your project's Gruntfile, add a section named bitbucket-pages to the data object passed into grunt.initConfig().

grunt.initConfig({
  'bitbucket-pages': {
    options: {
      baseDirectory: 'wwwroot',
      repository: 'https://[e-mail]/account/account.bitbucket.org.git'
    },
    publish: {
      src: ['wwwroot']
    }
  }
});

Run this task with grunt bitbucket_pages:publish.

This task will create a temporary clone of the repository specified by repository, copy the files/folders specified by src, commit all changes, then push to origin.

If there are files already in the repository that are not found in src they will be removed. The removed files can still be recovered from the git history if they are unintentionally deleted.

If src is used to point to a folder the folder will be copied recursively.

Options

options.baseDirectory

Required: false Type: String Default value: undefined

The base directory of the files copied from src.

By default the files will be copied into the repository relative to the working directory, typically the root of the project. If the site you want to publish lives in a sub folder of your project use this option to set that folder to be the root of the server.

For example say you had a html file that lived in

wwwroot/index.html

If you publish without setting the baseDirectory it will be published to

http://account.bitbucket.org/wwwroot/index.html

If you set the baseDirectory to wwwroot it will be published to

http://account.bitbucket.org/index.html

options.repository

Required: true Type: String Default value: undefined

The repository that the website should be published to.

options.siteName

Required: false Type: String Default value: undefined

Use this option if you want to publish multiple websites to a single bitbucket account. The site will be deployed in its own folder named after the specified siteName. Only files within this folder are modified meaning all other deployed sites will remain untouched.

If siteName was set to demo-site then the site would be visible at

http://account.bitbucket.org/demo-site/

Usage Examples

Default Options

In this example, the default options are used to publish all files in the root of the project, excluding Gruntfile.js, package.json and node_modules.

grunt.initConfig({
  'bitbucket-pages': {
  	publish: {
      options: {
        repository: 'https://[e-mail]/account/account.bitbucket.org.git'
      },
      src: ['**/*', '!Gruntfile.js', '!package.json', '!node_modules'],
  	}
  }
});

Files and Folders

In this example, the list of resources pointed to are a combination of files and folders. The folders will be copied recursively.

grunt.initConfig({
  'bitbucket-pages': {
    options: {
      baseDirectory: 'build/website',
      repository: 'https://[e-mail]/account/account.bitbucket.org.git'
    },
  	publish: {
      src: ['build/website/css', 'build/website/js/**/*.js', 'build/website/index.html']
  	}
  }
});

Multiple Sites

In this example, multiple sites deploying to a single bitbucket account have been configured.

grunt.initConfig({
  'bitbucket-pages': {
    options: {
      repository: 'https://[e-mail]/account/account.bitbucket.org.git'
    },
    site1: {
      options: {
        baseDirectory: 'site1-webroot'
      },
      src: ['site1-webroot']
    },
    site2: {
      options: {
        baseDirectory: 'site2-webroot'
      },
      src: ['site2-webroot']
    }
  }
});