jtasks: a swiss knife for Jekyll projects
jtasks (Jekyll tasks) is a collection of configurable Invoke tasks that provide simple, but powerful, interface to run both common and advanced routines in your Jekyll projects.
For example, let's run development server via Bundler, at host 0.0.0.0 (like in Jekyll 2), port 5000 (because I have multiple Jekyll projects served simultaneously), generate output into dist folder, including drafts and enabling incremental build:
# using jtasks:
$ invoke serve -bdi
# common way:
$ bundle exec jekyll serve --destination ./dist/ --host 0.0.0.0 --port 5000 --incremental --drafts
--destination, --host and --port are configured as global variables at the settings part of the script. This allows flexible setup of jtasks on per-project basis.
How to Use
inv[oke] task1 [--task1-opts] ... taskN [--taskN-opts]
Examples:
Build the site with Bundler:
$ inv build -b
Serve site with Bundler including draft posts:
$ inv serve -bd
Notify Google and Bing about your sitemap updates:
$ inv notify -gb
Create a new post with the given title:
$ inv post "My awesome post"
Start development server and fire up default browser to preview resulted site:
$ inv serve preview
List all posts and drafts:
$ inv list -d
Remove generated site:
$ inv clean
Check site for compatibility problems and URL conflicts:
$ inv doctor
Installation
Copy tasks.py file into the base folder of your Jekyll site.
You also need Python (2.7+ or 3.3+) with Invoke package:
Configuration
All settings are available at the top of the tasks.py file:
# === Settings ===
# Project directories
_site_dest = "./_site/" # Dir where Jekyll will generate site
_posts_dest = "./_posts/" # Dir with posts
_drafts_dest = "./_drafts/" # Dir with drafts
# Global options
_hostname = '127.0.0.1' # Listen given hostname
_port = '4000' # Listen given port
_bundle_exec = False # Run commands with Bundler
_fpolling = False # Force watch to use polling
_incremental = False # Enable incremental build (Jekyll 3 and higher!)
# Post settings
_post_ext = '.md' # Post files extension
# Notification settings (your sitemap location)
_sitemap_url = 'http://www.example.com/sitemap.xml'
From the box, jtasks uses Jekyll 3 default configuration settings. They can be easily modified for your project-specific needs. E.g. if we always need to run all tasks via Bundler, it is possible to set _bundle_exec = True and now all tasks (where applicable) will be executed using bundle exec:
$ inv build
# Same as:
$ bundle exec jekyll build --destination ./_site/
Available tasks
Currently, following tasks are supported:
$ inv --list
Available tasks:
build Build the site.
clean Clean the site.
doctor Search site and print specific deprecation warnings.
list List all posts.
notify Notify various services about sitemap update.
post Create a new post.
preview Launches default browser for previewing generated site.
serve Serve the site locally.
build
$ inv --help build
Docstring:
Build the site.
jekyll build [options]
Options:
-b, --bundle-exec Build site via Bundler.
-d, --drafts Build site including draft posts.
-i, --incremental-build Rebuild only posts and pages that have changed.
serve
$ inv --help serve
Docstring:
Serve the site locally.
jekyll serve [options]
Options:
-b, --bundle-exec Run Jekyll development server via Bundler.
-d, --drafts Process and render draft posts.
-f, --force-polling Force watch to use polling.
-i, --incremental-build Rebuild only posts and pages that have changed.
clean
$ inv --help clean
Docstring:
Clean the site.
Removes site output and metadata file without building.
Options:
none
doctor
$ inv --help doctor
Docstring:
Search site and print specific deprecation warnings.
jekyll doctor
Options:
-b, --bundle-exec Run doctor via Bundler.
post
$ inv --help post
Docstring:
Create a new post.
Options:
-d, --drafts Create draft post.
-t STRING, --title=STRING Post title.
list
$ inv --help list
Docstring:
List all posts.
Options:
-d, --drafts Include draft posts.
notify
$ inv --help notify
Docstring:
Notify various services about sitemap update.
Options:
-b, --bing Notify Bing about sitemap updates.
-g, --google Notify Google about sitemap updates.
preview
$ inv --help preview
Docstring:
Launches default browser for previewing generated site.
`build` and/or `serve` tasks should be launched manually in advance,
depending on desired options.
Options:
none
License
Distributed under the terms of the MIT License.
