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:

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.

Not working on bundler for Windows

Issue Report

Submitted: 08/16/2022 1:40 PM PDT

Problem

Cake module does not work on Ruby / bundler mingw installations for jekyll local tests.

What happens?

Given dough:

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

var target = Argument("target", "BuildJekyll");
var configuration = Argument("configuration", "Debug");

Task("CleanJekyll")
    .Does(() =>
{
    JekyllClean(settings => settings
        .SetLogLevel(JekyllLogLevel.Verbose)
        .SetWorkingDirectory("./docs"));
});

Task("BuildJekyll")
    .IsDependentOn("CleanJekyll")
    .Does(() =>
{
    JekyllBuild(settings => settings
        .SetLogLevel(JekyllLogLevel.Verbose)
        .SetWorkingDirectory("./docs"));
});

RunTarget(target);

Result is:

========================================
CleanJekyll
========================================
An error occurred when executing task 'CleanJekyll'.
Error: An error occurred trying to start process '"C:/tools/Ruby31-x64/Ruby31-x64/bin/bundle"' with working directory 'D:/source/repos/work/ecs-saber/docs'. The specified executable is not a valid application for this OS platform.

System Configuration

Please note that jekyll builds fine with bundler outside of the cake tool on this system.

Host OS

OS Name	Microsoft Windows 11 Home
Version	10.0.22000 Build 22000

Ruby Version

PS D:\source\repos\work\ecs-saber> ruby -v
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]

Bundler Version

PS D:\source\repos\work\ecs-saber> bundler -v
Bundler version 2.3.20

Jekyll Version

PS D:\source\repos\work\ecs-saber> jekyll -v
jekyll 4.2.2

Expected Result

Building jekyll works with bundler outside of the cake tool works, indicating that the cake tool should. It does not as the build fails with an error about the operating system set up being unconventional.

Suggested Fix

Add configuration settings to check for .bat or .cmd files, so that the build will succeed when the user has a working configuration. The error is due to a .bat command launcher for mingw being used when on ruby >= 3.0.0 instead of a .cmd command launcher, that the cake tool does not recognize or is able to check for. The fix will account for both scenerios.

cake-contrib / cake.jekyll Goto Github PK

cake.jekyll's Introduction