What it is

A Rakefile to simplify some operations on your jekyll websites.

Main features:

• Support to common tasks, such as building and previewing
• Compass compilation and watching
• Commands for checking links, publishing a post with a summary of the changes since last deployment
• URL substitutions, to simplify deployment to sub-URIs
• Management of different configurations (similar to Rails)
• Integration with git repositories: check there are no upstream changes before deploying; commit and push on publication
• Deployment via rsync
• Publishing to Github

Notice that Jekyll has introduced many new features since this Rakefile was first released. One, for instance, is support for compass compilation; another is improved documentation related to deployment on non-root URLs. This Rakefile is quite configurable in the functions it provides, so you might still find it useful, even if you are using some of the new features provided by Jekyll or even if you are deploying your website using Github pages.

Installation

1. Download this repository
2. Put the files in your jekyll website directory
3. If needed, change the values of the variables in _rake_configuration.yml
4. Start using it!

Note. The _rake_configuration.yml can be safely deleted if you are using the default values or if you prefer to set the variables directly in the Rakefile.

Typical Usage Scenario

Specify the deployment configuration in the _config_deploy.yml file (see next section for details).

Then use the Rakefile as you wish. For instance:

rake create_post[,"A post"]
rake preview
rake deploy

Managing Relative and absolute URLs

Using relative URLs in a Jekyll site can be tricky. Think of a situation in which you are using the same layout for pages at different levels of nesting. Relative links in the layout will be resolved differently for pages at different levels of nesting and, thus, will work only for some of the pages, while failing for others. On the other hand, using absolute URLs in the layout might break the possibility of previewing a website, since absolute links might not solve correctly with respect to http://localhost:4000. Moreover, if you want your website to remain portable, it is a good idea to make the deployment URL into a configuration variable, which can be set once and for all in a single location.

One way to address the issue mentioned above is using the baseurl configuration variable, which can be used to make all URLs absolute and which can be overridden using a command-line argument when previewing. The point is that the value has to be set every time you run jekyll.

This Rakefile adopts a similar solution. It allows users to define a variable, e.g. url, and set this variable in a configuration file, e.g., _config_deploy.yml to the URL to be used when deploying. The Rakefile automatically uses the value read from _config_deploy.yml when deploying and http://localhost:4000 when previewing. This ensures that URLs are correctly resolved in all the environments.

The approach, which is inspired by Rails, can be used to define different sets of variables for previewing and deploying. This is useful, for instance, when using JAPR, a plugin which allows to bundle assets. In fact, you might want to compile the assets only when deploying and leave them unbundled when debugging/previewing. This can be achieved setting the JAPR bundle variable, which needs to be set to false when previewing and to true when deploying.

More in details, when running:

• rake preview, the Rakefile instructs Jekyll to read the _config.yml file only
• rake deploy (or rake build), the Rakefile instructs Jekyll to read the content of both _config.yml and _config_deploy.yml

This allows to provide specific settings for deployment, overriding those set in _config.yml, if necessary.

Notice that you can also pass an optional argument to rake deploy (rake build), which specifies the environment you want to use. Thus, for instance:

• rake build[testing] will instruct Jekyll to read the content of both _config.yml and _config_testing.yml. Of course you can replace testing with any environment you prefer. This, for instance, allows you to mirror the same website on different machines or to test a deployment before actually making your website available.

Deploying your Website

Deploying with rsync

If your website is hosted by a provider which supports rsync, this Rakefile can deploy the website for you. More in details, a special variable deploy_dir can be defined in _config_deploy.yml, to specify the directory where the Jekyll site has to be deployed.

For instance, _config_deploy.yml could look like:

baseurl: http://www.example.com/some/subdir
deploy_dir: webuser@example.com:/some/directory

which instructs the Rakefile to replace baseurl with http://www.example.com/some/subdir in your pages and copying the _site files to @webuser@example.com:/some/directory@.

Publishing to Github

If your website is hosted on Github, you can use the deploy_github task to publish the website.

The behavior is fairly simple: the task pushes the local gh_pages branch to the corresponding remote branch. The main advantage with respect to directly invoking git push origin gh_pages from the command line is some bookkeeping (e.g., checking the push command won’t be rejected and updating the _last_deploy file).

Integration with Git

If you are using git to manage the sources of your website your code has to be in sync with the remote repository before publishing your website. If this is not the case, in fact, you will most likely deploy an old version of the repository, causing a regression.

The simplest solution to this issue is using Github pages or a custom post-commit hook (once again, look at Jekyll’s documentation). In this case, in fact, the deployment of the website is managed directly by git after a successful push. This ensures that websites can be deployed only when the version being pushed builds upon the latest version committed on the repository and published.

However, if you cannot use Github pages or define a custom hook, this Rakefile can check the status of the default remote before deploying and, optionally, commit and push changes to the default remote after deploying a website. The first behavior (warning if you are trying to publish an old version of your repository) is set by default. If you want to commit and push on deploy, you need to set the variable $git_autopush to true in _rake_configuration.rb.

Commands

The commands made available are:

rake build                                     # Build for deployment (but do not deploy)
rake check_links                               # Check links for site already running on localhost:4000
rake clean                                     # Clean up generated site
rake create_post[date,title,category,content]  # Create a post
rake deploy                                    # Build and deploy to remote server via rsync
rake deploy_github                             # Build and deploy to Github
rake list_changes                              # Print the file changed since last deploy
rake post_changes                              # Create a post listing all changes since last deploy
rake preview                                   # Preview on local machine (server with --auto)

Change Log

• version 2.1 adds an (experimental) task to deploy to Github

• version 2.0 changes quite radically the behaviour, exploiting some of the changes made to Jekyll. The Rakefile does not mess up with _config.yml anymore, but it expects a _config_deploy.yml (or similar) file to specify the deployment directives. The value of $deploy_dir$ is now specified in _config_deploy.yml; this allows to keep the configuration variables together; support multiple deployment configurations; give the _rake_configuration.rb file up, if the default settings (compass, git check, …) are ok. The new git checks verify that the local repository is in sync with the remote and optionally pushes all changes to the remote after a commit.

Caveats

If you do not put the following directive in your _config.yml file:

exclude: ['Rakefile']

the Rakefile will end up in your website. (It shouldn’t do any harm if you publish it.)

License

Distributed under the terms of the MIT License