Jekyll::Tailwindcss

Bring the fun of building with TailwindCSS into your Jekyll project (without any JavaScript)

TL;DR This gem borrows heavily from tailwindcss-rails to provide platform-specific tailwind executables and provide a smooth developer experience in Jekyll projects

Much like the Rails gem, this gem wraps the standalone executable version of the Tailwind CSS v3 framework. It installs these as platform-specific executables, so there are separate underlying gems per platform, but the correct gem will automatically be picked for your platform.

“Because building a great jekyll site shouldn’t require a node_modules folder

Installation

Install the gem in your jekyll project's Gemfile by executing the following:

bundle add jekyll-tailwindcss

Add the plugin to your list of jekyll plugins in _config.yml

plugins:
  - jekyll-tailwindcss

Tailwind Configuration

This plugin requires you to have a tailwind configuration file (tailwind.config.js) at the root level of your project, which can be generated by running:

bundle exec jekyll-tailwindcss init

Tailwind will include the CSS for the classes found in content directories. For most jekyll sites, this would work well.

  content: [
    "./_drafts/**/*.md",
    "./_includes/**/*.html",
    "./_layouts/**/*.html",
    "./_pages/*.{html,md}",
    "./_posts/*.md",
    "./*.{html,md}",
  ],

Learn more at https://tailwindcss.com/docs/configuration

Usage

bundle exec jekyll serve # or build

Any *.css file processed by jekyll [^1] that contains the @tailwind directive will now be converted through the Tailwind CLI.

[^1]: Jekyll will process any file that begins with yaml frontmatter

Examples

A CSS file with frontmatter and @tailwind directives:

/* assets/css/styles.css */
---
# This yaml frontmatter is required for jekyll to process the file
---

@tailwind base;
@tailwind components;
@tailwind utilities;

.btn {
  @apply font-bold py-2 px-4 rounded !important;
}

will be converted to

/* _site/assets/css/styles.css */

/*
 * Tailwind generated CSS 
 * ...
 */

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem on your local machine, run bundle exec rake install.

Updating to the latest upstream tailwindcss version

Update lib/tailwindcss/upstream.rb with the upstream version.

Run bundle exec rake clobber and then bundle exec rake download to ensure the tailwindcss binaries can be downloaded and you have the correct versions on the local disk.

Testing this gem

Running the test suite

The unit tests are run with bundle exec rspec

There is an additional integration test which runs in CI, spec/integration/user_journey_test.sh which you may also want to run.

Testing in a Jekyll project

If you want to test modifications to this gem, you must run rake download once to download the upstream tailwindcss executables.

Then you can point your Jekyll project's Gemfile at the local version of the gem as you normally would:

gem "jekyll-tailwindcss", path: "/path/to/jekyll-tailwindcss"

Cutting a release

• bump the version
  • update lib/jekyll-tailwindcss/version.rb
  • update CHANGELOG.md
  • commit and create a git tag
• build the native gems:
  • bundle exec rake clobber to clean up possibly old tailwindcss executables
  • bundle exec rake package
• push
  • for g in pkg/*.gem ; do gem push $g ; done
  • git push
• announce
  • create a release at https://github.com/vormwald/jekyll-tailwindcss/releases

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vormwald/jekyll-tailwindcss. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Jekyll::Tailwindcss project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.