jekyll-tailwindcss 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e1e29ca0abd9c5830429366d0552d685446274bda03e353ee6829e2bb946296
-  data.tar.gz: 1cd3dd8fd880efdb33118309492697061c624e046abd72cc5540e98db9bee90c
+  metadata.gz: 7ee5a9792a9b5cf2255d635a81aec5e938c6cda3b3ec233d9fac8e04ce92291f
+  data.tar.gz: 9b12d099c03f0d30c964af19b3ee416963ea832c17c56b3d3c0dda6fb61d3069
 SHA512:
-  metadata.gz: 58bfbab5c38628acc762375d3d6f8211ce6cb302b6803bbff3428f345efafe1e29f4087739dfc05fb855e65149c749c18b8206d3677015837fb2c159207cea5b
-  data.tar.gz: 67c4d4efafa86cc2972cc1db7e357cfdd65e14583ed5e27138a692e94a8f8af198555184e717db19e19046cae215f2680f04358e2182a64a6f6d1df75eebbf8a
+  metadata.gz: 96fe15592fa421840b7c76dd50560696f7fb0dadf20ab19e1d9aad852c1c5e7c1dd267e1cf7967826bfc17e90189afcff03562b3d611dd9e405d5351df10544c
+  data.tar.gz: bee07784b16ac19531147e2e554a9874e89bc0e0b73a8c07b28ffb13da8f70f88dfb00faa93f68876f6d94816f9ac55107a19b65fe7e2e3bb2c2422ca0d99af7

data/README.md

@@ -1,20 +1,15 @@
 # Jekyll::Tailwindcss
 
-Bring the fun of building with TailwindCSS into your Jekyll project (without any JavaScript)
+Bring the joy of building with TailwindCSS into your Jekyll project (without any JavaScript)
 
-**TL;DR** This gem borrows _heavily_ from [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) to provide platform-specific tailwind executables and provide a smooth developer experience in Jekyll projects
+**TL;DR** This gem uses [tailwindcss-ruby](https://github.com/rails/tailwindcss-ruby) to provide platform-specific tailwind executables and enables a smooth developer experience in Jekyll projects
 
-> _"Because building a great jekyll site shouldn't require a `node_modules` folder"_
+> _"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 --group jekyll_plugins
-```
+## Installation
 
-Or by adding the gem manually
+Add the gem to your Jekyll project's Gemfile
 
 ```ruby
 # Gemfile
@@ -25,10 +20,12 @@ group :jekyll_plugins do
 end
 ```
 
-> [!NOTE]
-> By adding this gem to the jekyll_plugins group, you don't need to explicitly configure it in `_config.yml`.
+Run `bundle install`
+
+> [!TIP]
+> By adding this gem to the `:jekyll_plugins` group, you don't need to explicitly configure it in `_config.yml`.
 
-### Choosing a specific version of tailwindcss
+### Optional: Choosing a specific version of tailwindcss
 
 This gem uses the latest TailwindCSS by default. However since CLI versions are managed by the `tailwindcss-ruby` gem, it supports older versions as well.
 
@@ -56,7 +53,7 @@ tailwindcss:
   config: "./tailwind.config.js"
 ```
 
-Tailwind will generate CSS for the classes found in `content` directories. For most jekyll sites, this would work well.
+Tailwind will generate CSS for the classes found in `content` directories. For most Jekyll sites, this would work well.
 
 ```js
 // ./tailwind.config.js
@@ -83,7 +80,7 @@ Any CSS file with frontmatter and `@tailwind` directives will be converted.
 ```css
 /* assets/css/styles.css */
 ---
-# This yaml frontmatter is required for jekyll to process the file
+# This yaml frontmatter is required for Jekyll to process the file
 ---
 
 @tailwind base;
@@ -101,14 +98,21 @@ will be converted to
 /* _site/assets/css/styles.css */
 
 /*
- * Tailwind generated CSS 
+ * Tailwind generated CSS
  * ...
  */
 ```
 
 ### PostCSS Support
 
-This gem includes basic PostCSS support. If a `postcss.config.js` file is included in your `_config.yml`, the Tailwind CLI will be invoked with the `--postcss` flag.
+> [!WARNING]
+> PostCSS configuration is considered an advanced use case and is outside the scope of this gem.
+> It is possible that support be removed in future versions of this gem. If needed, you should look to run your Tailwind builds with node.
+
+That said... This gem includes basic PostCSS support. If a `postcss.config.js` file is included in your `_config.yml`, the Tailwind CLI will be invoked with the `--postcss` flag.
+
+Users should verify their PostCSS setup outside this gem by running:
+ `bundle exec tailwindcss --postcss postcss.config.js`
 
 ```yaml
 tailwindcss:
@@ -116,58 +120,61 @@ tailwindcss:
   postcss: "./postcss.config.js" # OPTIONAL, only if you have a postcss config file
 ```
 
-> [!NOTE]
-> PostCSS configuration is considered an advanced use case and is outside the scope of this gem. Users should verify their PostCSS setup outside this gem by running:
-> `bundle exec tailwindcss --postcss postcss.config.js`
 
 </details>
 
 ## Usage
 
-```sh
-bundle exec jekyll serve # or build
-```
+> See an example repo at https://github.com/vormwald/jekyll-blahg
 
-Any `*.css` file processed by jekyll [^1] that contains the `@import "tailwindcss";` [directive](https://tailwindcss.com/docs/functions-and-directives#config) will be converted through the Tailwind CLI.
+### Setup
+You'll need 2 files to make this work:
 
-[^1]: Jekyll will process any file that begins with yaml [frontmatter](https://jekyllrb.com/docs/front-matter/)
+**File 1: `./_tailwind.css`**
 
-### Example
-Any CSS file with frontmatter and `@import "tailwindcss";` will be converted.
-
-Your CSS file
+This file acts as your tailwind configuration file. Import "tailwindcss" and any custom CSS here.
 
 ```css
-/* assets/css/styles.css */
----
-# This yaml frontmatter is required for jekyll to process the file
----
-
 @import "tailwindcss";
 
-.btn {
-  @apply rounded border border-gray-300;
-}
+/* ... any other imports or css classes */
 ```
 
-will be converted to
 
-```css
-/* _site/assets/css/styles.css */
+**File 2: `./assets/css/styles.tailwindcss`**
 
-/*
- * Tailwind generated CSS 
- * ...
-  .btn {
-    border-radius: 0.25rem;
-    border-style: var(--tw-border-style);
-    border-width: 1px;
-    border-color: var(--color-gray-300);
-  }
- * ...
- */
+Place this file wherever you'd like your site's tailwind CLI generated content to go: `assets/css/your_css_file.tailwindcss` -> `__site/assets/css/your_css_file.css`
+
+It must contain yaml frontmatter to be processed by Jekyll [^1]
+
+```yaml
+---
+# This file will be converted to __site/assets/css/styles.css
+---
+This file is just a placeholder. It's content will be replaced by output from the tailwindcss CLI.
 ```
 
+> [!NOTE]
+> Why the 2 files?
+>
+> This is a compromise to allow the [TailwindCSS intellisense](https://tailwindcss.com/docs/editor-setup#intellisense-for-vs-code) plugin to work. (It cannot parse a CSS file with frontmatter, so we keep it seperate)
+>
+> The `_tailwind.css` file serves as the tailwindcss config file.
+> If you'd rather set keep this file somewhere else, you can do so by setting the `tailwindcss.config_file` option in `_config.yml`:
+>
+> ```yaml
+> tailwindcss:
+>   config_file: ./_data/tailwind.css
+> ```
+
+### Building the Jekyll site
+
+```sh
+bundle exec jekyll serve
+```
+[^1]: Jekyll will process any file that begins with yaml [frontmatter](https://jekyllrb.com/docs/front-matter/)
+
+
 ### Minification
 
 The `--minify` flag is automatically added when the `JEKYLL_ENV` environment variable is present and set to anything other than `development`. [Jekyll Docs](https://jekyllrb.com/docs/configuration/environments/)

data/lib/jekyll/converters/css.rb

@@ -0,0 +1,70 @@
+require "open3"
+
+module Jekyll
+  module Converters
+    class Css < Converter
+      safe true
+      priority :low
+
+      def matches(ext)
+        /^\.css$/i.match?(ext)
+      end
+
+      def output_ext(ext)
+        # At this point, we will have a CSS file
+        ext
+      end
+
+      def convert(content)
+        return content unless /@tailwind|@import ['"]tailwindcss/i.match?(content)
+        if config_path.nil? && tailwind_v3_syntax?(content)
+          Jekyll.logger.error "Jekyll Tailwind:", "to use tailwind v3 you need to include a config path in _config.yml"
+          return content
+        end
+
+        dev_mode = Jekyll.env == "development"
+        Jekyll.logger.info "Jekyll Tailwind:", "Generating #{dev_mode ? "" : "minified "}CSS"
+
+        compile_command = ::Tailwindcss::Commands
+          .compile_command(debug: dev_mode, config_path: config_path, postcss_path: postcss_path)
+          .join(" ")
+
+        output, error = nil
+        Open3.popen3(tailwindcss_env_options, compile_command) do |stdin, stdout, stderr, _wait_thread|
+          stdin.write content # write the content of *.tailwindcss to the tailwindcss CLI as input
+          stdin.close
+          output = stdout.read
+          error = stderr.read
+        end
+        Jekyll.logger.warn "Jekyll Tailwind:", error unless error.nil?
+
+        output
+      rescue => e
+        Jekyll.logger.error "Jekyll Tailwind:", e.message
+        content
+      end
+
+      private
+
+      def tailwind_v3_syntax?(content)
+        return false if content.include?("@plugin")
+
+        content.include?("@tailwind")
+      end
+
+      def tailwindcss_env_options
+        # Without this ENV you'll get a warning about `Browserslist: caniuse-lite is outdated`
+        # Since we're using the CLI, we can't update the data, so we ignore it.
+        {"BROWSERSLIST_IGNORE_OLD_DATA" => "1"}
+      end
+
+      def config_path
+        @config.dig("tailwindcss", "config")
+      end
+
+      def postcss_path
+        @config.dig("tailwindcss", "postcss")
+      end
+    end
+  end
+end

data/lib/jekyll/converters/tailwindcss.rb

@@ -5,33 +5,33 @@ module Jekyll
     class Tailwindcss < Converter
       safe true
       priority :low
+      EXTENSION_PATTERN = %r{^\.tailwind(css)?$}i
 
       def matches(ext)
-        /^\.css$/i.match?(ext)
+        EXTENSION_PATTERN.match? ext
       end
 
       def output_ext(ext)
-        # At this point, we will have a CSS file
-        ext
+        ".css"
       end
 
       def convert(content)
-        return content unless /@tailwind|@import ['"]tailwindcss/i.match?(content)
-        if config_path.nil? && tailwind_v3_syntax?(content)
-          Jekyll.logger.error "Jekyll Tailwind:", "to use tailwind v3 you need to include a config path in _config.yml"
-          return content
+        unless valid_tailwindcss_gem_version?
+          print_tailwind_v3_warning
+
+          return
         end
 
         dev_mode = Jekyll.env == "development"
         Jekyll.logger.info "Jekyll Tailwind:", "Generating #{dev_mode ? "" : "minified "}CSS"
 
         compile_command = ::Tailwindcss::Commands
-          .compile_command(debug: dev_mode, config_path: config_path, postcss_path: postcss_path)
+          .compile_command(debug: dev_mode)
           .join(" ")
 
         output, error = nil
-        Open3.popen3(tailwindcss_env_options, compile_command) do |stdin, stdout, stderr, _wait_thread|
-          stdin.write content # write the content of *.tailwindcss to the tailwindcss CLI as input
+        Open3.popen3(compile_command) do |stdin, stdout, stderr, _wait_thread|
+          stdin.write tailwind_content
           stdin.close
           output = stdout.read
           error = stderr.read
@@ -46,24 +46,30 @@ module Jekyll
 
       private
 
-      def tailwind_v3_syntax?(content)
-        return false if content.include?("@plugin")
-
-        content.include?("@tailwind")
+      def tailwind_content
+        "@import '#{tailwind_css_path}';"
       end
 
-      def tailwindcss_env_options
-        # Without this ENV you'll get a warning about `Browserslist: caniuse-lite is outdated`
-        # Since we're using the CLI, we can't update the data, so we ignore it.
-        {"BROWSERSLIST_IGNORE_OLD_DATA" => "1"}
+      def tailwind_css_path
+        @config.dig("tailwindcss", "css_path") || "./_tailwind.css"
       end
 
-      def config_path
-        @config.dig("tailwindcss", "config")
+      def valid_tailwindcss_gem_version?
+        gem_spec = Gem.loaded_specs["tailwindcss-ruby"]
+        return false unless gem_spec
+
+        Gem::Version.new(gem_spec.version) >= Gem::Version.new("4.0.0")
+      rescue
+        # If anything goes wrong (gem not found, version format issues, etc.)
+        false
       end
 
-      def postcss_path
-        @config.dig("tailwindcss", "postcss")
+      def print_tailwind_v3_warning
+        Jekyll.logger.warn "Jekyll Tailwind:", "You're using a .tailwindcss file extension, but your tailwindcss-ruby gem is below version 4.0."
+        Jekyll.logger.warn "Jekyll Tailwind:", "The .tailwindcss extension is only supported in v4.0.0 and above."
+        Jekyll.logger.warn "Jekyll Tailwind:", "Please either:"
+        Jekyll.logger.warn "Jekyll Tailwind:", "  - Upgrade with: bundle update tailwindcss-ruby"
+        Jekyll.logger.warn "Jekyll Tailwind:", "  - Rename your file to use .css extension with @import \"tailwindcss\" syntax"
       end
     end
   end

data/lib/jekyll-tailwindcss/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Tailwindcss
-    VERSION = "0.6.2"
+    VERSION = "0.7.0"
   end
 end

data/lib/jekyll-tailwindcss.rb

@@ -2,6 +2,7 @@
 
 require "jekyll"
 require_relative "jekyll-tailwindcss/version"
+require_relative "jekyll/converters/css"
 require_relative "jekyll/converters/tailwindcss"
 require_relative "tailwindcss/commands"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-tailwindcss
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Mike Vormwald
 bindir: exe
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tailwindcss-ruby
@@ -34,6 +34,7 @@ files:
 - Rakefile
 - lib/jekyll-tailwindcss.rb
 - lib/jekyll-tailwindcss/version.rb
+- lib/jekyll/converters/css.rb
 - lib/jekyll/converters/tailwindcss.rb
 - lib/tailwindcss/commands.rb
 homepage: https://github.com/vormwald/jekyll-tailwindcss