README.md

Cake.Jekyll

Cross-platform addin for the Cake build automation system that makes Jekyll available in Cake builds. Cake.Jekyll works on Windows, Linux, and macOS. Jekyll is a blog-aware, static site generator in Ruby.

Give a Star! ⭐

If you like or are using this project please give it a star. Thanks!

Prerequisites

In order to use Cake.Jekyll, you will need to install Jekyll first. By default, Cake.Jekyll uses Bundler to run Jekyll, but this can be disabled via settings if you want to run Jekyll directly. For more information on why using Bundler might be a good idea, read "Using Jekyll with Bundler".

Getting started 🚀

This addin exposes the functionality of Jekyll to the Cake DSL by being a very thin wrapper around its command line interface; this means that you can use the Jekyll commands you would normally use via command line, but with a Cake-friendly interface.

First of all, you need to import Cake.Jekyll in your build script by using the addin directive:

#addin "nuget:?package=Cake.Jekyll&version=3.0.0"

Make sure the &version= attribute references the latest version of Cake.Jekyll compatible with the Cake runner that you are using. Check the compatibility table to see which version of Cake.Jekyll to choose.

Next, call the Jekyll commands you'd like to use:

#addin "nuget:?package=Cake.Jekyll&version=3.0.0"

Task("Build")
    .Does(() =>
{
    JekyllBuild(settings => settings
        .RenderDrafts()
        .EnableIncrementalBuild()
        .EnableTrace()
    );
});

RunTarget("Build");

Jekyll command aliases available

Method	Description	Settings
JekyllClean	Clean your site (removes site output and metadata file) without building	JekyllCleanSettings
JekyllBuild	Build your Jekyll site	JekyllBuildSettings
JekyllServe	Serve your Jekyll site locally	JekyllServeSettings
JekyllDoctor	Search your site and print specific deprecation warnings	JekyllDoctorSettings
JekyllNew	Create a new Jekyll site scaffold	JekyllNewSettings
JekyllNewTheme	Create a new Jekyll theme scaffold	JekyllNewThemeSettings
JekyllVersion	Print the name and version	N/A

Usage Examples

In the sample folder, there are several examples of usage:

• Simple pipeline with JekyllxxxSettings instance
• Simple pipeline using the configurator pattern

JekyllClean

JekyllClean settings. Click to expand.

Property	Extension Method	Description
Configuration	WithConfiguration	Custom configuration file
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
Future	PublishFuture	Publishes posts with a future date
LimitPosts	LimitPosts	Limits the number of posts to parse and publish
Watch	EnableWatch	Watch for changes and rebuild
BaseUrl	SetBaseUrl	Serve the website from the given base URL
ForcePolling	ForcePolling	Force watch to use polling
Lsi	UseLsi	Use LSI for improved related posts
Drafts	RenderDrafts	Render posts in the _drafts folder
Unpublished	RenderUnpublished	Render posts that were marked as unpublished
DisableDiskCache	DisableDiskCache	Disable caching to disk in non-safe mode
IncrementalBuild	EnableIncrementalBuild	Enable incremental rebuild
StrictFrontMatter	UseStrictFrontMatter	Fail if errors are present in front matter
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
LogLevel	SetLogLevel	Print verbose output or silence output
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllBuild

JekyllBuild settings. Click to expand.

Property	Extension Method	Description
Configuration	WithConfiguration	Custom configuration file
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
Future	PublishFuture	Publishes posts with a future date
LimitPosts	LimitPosts	Limits the number of posts to parse and publish
Watch	EnableWatch	Watch for changes and rebuild
BaseUrl	SetBaseUrl	Serve the website from the given base URL
ForcePolling	ForcePolling	Force watch to use polling
Lsi	UseLsi	Use LSI for improved related posts
Drafts	RenderDrafts	Render posts in the _drafts folder
Unpublished	RenderUnpublished	Render posts that were marked as unpublished
DisableDiskCache	DisableDiskCache	Disable caching to disk in non-safe mode
IncrementalBuild	EnableIncrementalBuild	Enable incremental rebuild
StrictFrontMatter	UseStrictFrontMatter	Fail if errors are present in front matter
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
LogLevel	SetLogLevel	Print verbose output or silence output
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllServe

JekyllServe settings. Click to expand.

Property	Extension Method	Description
SslCertificate	UseSslCertificate	X.509 (SSL) certificate
SslKey	UseSslKey	X.509 (SSL) private key
Hostname	SetHostname	Host to bind to
Port	SetPort	Port to listen on
OpenUrl	OpenUrl	Launch your site in a browser
Detach	Detach	Run the server in the background
ShowDirListing	ShowDirListing	Show a directory listing instead of loading your index file
SkipInitialBuild	SkipInitialBuild	Skips the initial site build which occurs before the server is started
LiveReload	UseLiveReload	Use LiveReload to automatically refresh browsers
LiveReloadIgnore	WithLiveReloadIgnore	Files for LiveReload to ignore
LiveReloadMinDelay	SetLiveReloadMinDelay	Minimum reload delay
LiveReloadMaxDelay	SetLiveReloadMaxDelay	Maximum reload delay
LiveReloadPort	SetLiveReloadPort	Port for LiveReload to listen on
Configuration	WithConfiguration	Custom configuration file
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
Future	PublishFuture	Publishes posts with a future date
LimitPosts	LimitPosts	Limits the number of posts to parse and publish
Watch	EnableWatch	Watch for changes and rebuild
BaseUrl	SetBaseUrl	Serve the website from the given base URL
ForcePolling	ForcePolling	Force watch to use polling
Lsi	UseLsi	Use LSI for improved related posts
Drafts	RenderDrafts	Render posts in the _drafts folder
Unpublished	RenderUnpublished	Render posts that were marked as unpublished
DisableDiskCache	DisableDiskCache	Disable caching to disk in non-safe mode
IncrementalBuild	EnableIncrementalBuild	Enable incremental rebuild
StrictFrontMatter	UseStrictFrontMatter	Fail if errors are present in front matter
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
LogLevel	SetLogLevel	Print verbose output or silence output
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllDoctor

JekyllDoctor settings. Click to expand.

Property	Extension Method	Description
Configuration	WithConfiguration	Custom configuration file
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllNew

JekyllNew settings. Click to expand.

Property	Extension Method	Description
Path		Path to scaffold the site
Force	EnableForce	Force creation even if PATH already exists
Blank	EnableBlank	Creates scaffolding but with empty files
SkipBundle	SkipBundle	Skip bundle install
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllNewTheme

JekyllNewTheme settings. Click to expand.

Property	Extension Method	Description
Name		The name of the theme
CodeOfConduct	IncludeCodeOfConduct	Include a Code of Conduct
Source	SetSource	Custom source directory
Destination	SetDestination	Custom destination directory
SafeMode	EnableSafeMode	Safe mode
Plugins	WithPlugins	Plugins directory (defaults to ./_plugins)
Layouts	SetLayouts	Layouts directory (defaults to ./_layouts)
LiquidProfile	EnableLiquidProfile	Generate a Liquid rendering profile
Trace	EnableTrace	Show the full backtrace when an error occurs
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

JekyllVersion

JekyllNewTheme settings. Click to expand.

Property	Extension Method	Description
WorkingDirectory	SetWorkingDirectory	The working directory to run Jekyll
DoNotUseBundler	DoNotUseBundler	Run Jekyll directly, without Bundler

Compatibility

Cake.Jekyll is compatible with all Cake runners, and below you can find which version of Cake.Jekyll you should use based on the version of the Cake runner you're using.

Cake runner	Cake.Jekyll	Cake addin directive
3.0.0 or higher	3.0.0 or higher	#addin "nuget:?package=Cake.Jekyll&version=3.0.0"
2.0.0 - 2.3.0	2.0.0 - 2.1.0	#addin "nuget:?package=Cake.Jekyll&version=2.0.0"
1.0.0 - 1.3.0	1.0.0 - 1.0.1	#addin "nuget:?package=Cake.Jekyll&version=1.0.1"
< 1.0.0	N/A	(not supported)

Discussion

For questions and to discuss ideas & feature requests, use the GitHub discussions on the Cake GitHub repository, under the Extension Q&A category.

Release History

Click on the Releases tab on GitHub.

---

Copyright © 2021-2023 C. Augusto Proiete & Contributors - Provided under the MIT License.