Github Pages

Tool for publishing gh-pages the pro way. WIP

Install

  npm install --save-dev github-pages

Usage

CLI Usage

Publishes your github pages using the github API

Usage
  $ github-pages [options] [src]

  Options
  -r, --repo
  -t, --token
  -m  --commit-message
  -a  --commit-author
      --remote-ref
      --api-version
      --api-protocol
      --api-host
      --api-path
      --api-timeout

Examples
  $ github-pages -r user/repo -t $GH_TOKEN ./data
    > github-pages commit
    > github-pages push to user/repo

Not that the CLI arguments will always overwrite your github-pages configuration in your package.json file.

You only need to provide the repository, the token data and the src. The other arguments are optional.

WARNING The GithubPages will replace all the content of the given ref (heads/gh-pages by default) with the provided content. EVERYTHING that is not present in the src folder will be deleted in your branch. Have you made any mistake? Don't panic, GithubPages does not mess up with you git story. Just revert the commit. ;)

Configuration

All of the CLI options can be configured in the GithubPages section of your package.json. This allows you to modify the default behavior of the GithubPages command.

{
  "github-pages": {
    "api": {
      "version": "3.0.0",
      "protocol": "https",
      "host": "api.github.com",
      "pathPrefix": "",
      "timeout": 5000
    },
    "auth": {
      "type": "token",
      "token": "GH_TOKEN"
    },
    "remote": {
      "user": "user",
      "repo": "repo",
      "ref": "heads/gh-pages"
    },
    "commit": {
      "message": "commit made by me",
      "author": {
        "name": "author-name",
        "email": "author-email"
      }
    },
    "src": "./data"
  }
}

Arguments passed to the CLI will always take precedence over the configuration in package.json.

$GH_TOKEN: By default the token value is read from the environment var $GH_TOKEN. So if you don't want to set it in the configurations/cli, it will be read from $GH_TOKEN.

API Usage

  const GithubPages = require('github-pages');
  const config = require('package.json')['github-pages'];
 
  const pages = new GithubPages(config);
  pages.publish().then((res)=> {
    console.log('published');
    console.log(JSON.stringify(res, null, 2));
  }).catch((err)=> {
    console.error('error while publishing');
    console.error(JSON.stringify(err, null, 2));
  });

The GithubPages needs the complete configuration to be used (same file structure as described in package.json). If you don't want to provide all the configuration you can use the support file parse-config, passing the same arguments as the cli (using camelCase).

  const GithubPages = require('github-pages');
  const parseConfig = require('github-pages').parseConfig;
  const config = parseConfig({
    repo: 'user/repo',
    token: 'GH-TOKEN',
    remoteRef: 'heads/gh-pages',
    commitMessage: 'publishing from API.',
    commitAuthor: 'author-name <author-email>',
    apiVersion: '3.0.0',
    apiProtocol: 'https',
    apiHost: 'api.github.com',
    apiPath: '',
    apiTimeout: 5000
  }, './dist');
 
  const pages = new GithubPages(config);

The parseConfig method receives as a input the same structure used in the cli, which is a plain object with the cli params using camelCase, different from the one used in the package.json. Besides that, parseConfig method will try to preload the configuration from your package.json.

The parseConfig function will return null if the final configuration is invalid.

If you want to get the default configuration and change it yourself, then use if directly:

  const config = require('github-pages').parseConfig.default;
  /* => {
    api: {
      version: '3.0.0',
      protocol: 'https',
      host: 'api.github.com',
      pathPrefix: '',
      timeout: 5000
    },
    auth: { type: 'token', token: 'GH_TOKEN' },
    remote: { ref: 'heads/gh-pages' },
    commit: { message: 'github-pages publish.' }
  } */

If you want to validate your config object, you can use the helper function from parseConfig called isValid:

  const isValid = require('github-pages').parseConfig.isValid;
  isValid(config);
  // true|false

Integrating with Travis CI

To use GithubPages on your CI server, just install your lib and set your configuration. For a less intrusive aproach, just create a script in your package.json for GithubPages:

{
  "script": {
    "gh-pages": "github-pages -r user/repo ./dist"
  }
}

add the following to your .travis.yml:

after_success: npm run gh-pages

Remember that you need to provide the environment var GH_TOKEN. To learn how to provide this var in a secure and safe way, look at travis-encrypted-environment-variables or travis-repository-variables (recommended).

stack

• meow for cli
• github use of github api
• babel for transpiling es6 code to es5
• ava for testing
• nyc for code-coverage
• jscs lint
• eslint lint
• travis Continous integration
• codeclimate for resports on coverage & code analysis