What it is
A Rakefile to simplify some operations on your jekyll websites.
- 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
gitrepositories: check there are no upstream changes before deploying; commit and push on publication
- Deployment via
- 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.
1. Download this repository
2. Put the files in your jekyll website directory
3. If needed, change the values of the variables in
4. Start using it!
_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
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
rake build), the Rakefile instructs Jekyll to read the content of both
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_testing.yml. Of course you can replace
testingwith 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.
_config_deploy.yml could look like:
baseurl: http://www.example.com/some/subdir deploy_dir: firstname.lastname@example.org:/some/directory
which instructs the
Rakefile to replace
http://www.example.com/some/subdir in your pages and copying the
_site files to @email@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
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
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)
- 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
Rakefiledoes not mess up with
_config.ymlanymore, 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.rbfile 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.
If you do not put the following directive in your
Rakefile will end up in your website. (It shouldn’t do any harm if you publish it.)
Distributed under the terms of the MIT License