README.textile
h1. What it is
A Rakefile to simplify some operations on your "jekyll":http://jekyllrb.com 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":http://jekyllrb.com 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":http://jekyllrb.com or even if you are deploying your website using "Github pages":https://pages.github.com/.
h1. Installation
1. Download this repository
2. Put the files in your "jekyll":http://jekyllrb.com 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.
h1. 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:
<pre>
rake create_post[,"A post"]
rake preview
rake deploy
</pre>
h1. Managing Relative and absolute URLs
Using relative URLs in a "Jekyll":http://jekyllrb.com 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":https://github.com/kitsched/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":https://github.com/kitsched/japr's @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":http://jekyllrb.com to read the @_config.yml@ file only
* @rake deploy@ (or @rake build@), the Rakefile instructs "Jekyll":http://jekyllrb.com 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":http://jekyllrb.com 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.
h1. Deploying your Website
h2. 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":http://jekyllrb.com site has to be deployed.
For instance, @_config_deploy.yml@ could look like:
<pre>
baseurl: http://www.example.com/some/subdir
deploy_dir: webuser@example.com:/some/directory
</pre>
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@.
h2. 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).
h1. 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":https://pages.github.com/ 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":https://pages.github.com/ 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@.
h1. Commands
The commands made available are:
<pre>
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)
</pre>
h1. 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":http://jekyllrb.com. 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.
h1. Caveats
If you do not put the following directive in your @_config.yml@ file:
bc. exclude: ['Rakefile']
the @Rakefile@ will end up in your website. (It shouldn't do any harm if you publish it.)
h1. License
Distributed under the terms of the "MIT License":http://opensource.org/licenses/MIT