feat: upgrade from Tailwind v3 to v4

See Tailwind v4 breaking changes: https://tailwindcss.com/docs/upgrade-guide
See Hugo's new integration with Tailwind v4: https://gohugo.io/functions/css/tailwindcss/

Close #3211

Author: gcushen

.github/workflows/build-test-site.yaml

@@ -34,8 +34,11 @@ jobs:
             - recursive: false
               args: [--frozen-lockfile]
 
-#      - name: Install JS dependencies
-#        run: rm -rf node_modules && pnpm install --frozen-lockfile
+      - name: Install Tailwind v4 dependencies
+        run: |
+          cd modules/blox-tailwind
+          pnpm install --frozen-lockfile
+          cd ../..
 
       - name: Check for linting errors
         run: pnpm run lint:js  # TODO: also lint styles again once new rule errors resolved

modules/blox-bootstrap/layouts/_partials/page_metadata_authors.html

@@ -7,7 +7,7 @@
 
     {{- if gt $index 0 }}, {{ end -}}
     <span {{ if $highlight_name }}class="author-highlighted"{{end}}>
-      {{/* Effectively check the page's `_build` option as `_build` is not exposed in Hugo's Page object. */}}
+      {{/* Effectively check the page's `build` option as `build` is not exposed in Hugo's Page object. */}}
       {{- if .RelPermalink -}}
         <a href="{{.RelPermalink}}">{{.LinkTitle}}</a>
       {{- else -}}

modules/blox-tailwind/.npmrc

@@ -0,0 +1,4 @@
+# pnpm compatibility settings
+auto-install-peers=true
+strict-peer-dependencies=false
+public-hoist-pattern[]=*

modules/blox-tailwind/README.md

@@ -1,19 +1,67 @@
 # Hugo Blox Tailwind UI
 
-The Hugo Blox web framework utilising [TailwindCSS](https://tailwindcss.com/) and its [typography plugin](https://tailwindcss.com/docs/typography-plugin) for styling components.
+The Hugo Blox web framework utilizing [Tailwind CSS v4](https://tailwindcss.com/) with Hugo's native integration for styling components with Tailwind v4.
 
-See the Blog Starter Template for an example using this module.
+## Requirements
 
-## Development
+- Hugo v0.148.2+ (Extended Edition)
+- Node.js v20+ 
+- pnpm (see `packageManager` field in package.json)
+
+## Quick Start
+
+### 1. Install Dependencies
 
 ```bash
-hugo mod npm pack
-npm install
+pnpm install
 ```
 
-You need to add this to your `config.yaml` to enable Hugo's Tailwind integration:
+### 2. Run Development Server
+
+```bash
+hugo server
+```
+
+Tailwind CSS is processed automatically by Hugo using the `css.TailwindCSS` function.
+
+## Features
+
+- **Tailwind CSS v4**: Latest version with improved performance over Tailwind v3
+- **Hugo Native Integration**: Uses Hugo's built-in `css.TailwindCSS` function
+- **Dynamic CSS Generation**: Only includes utilities actually used in your content for ultra-fast page loads
+- **No Pre-compilation**: CSS is generated on-demand (previously Tailwind v3 was pre-compiled in Hugo Blox as `wc.min.css`)
+- **Community Components**: Community components work seamlessly without manual compilation
+
+## Configuration
+
+The Tailwind configuration is now in CSS format at `assets/css/main.css` using the `@theme` directive. The configuration includes:
+
+- Hugo Blox color schemes (primary, secondary, neutral)
+- Typography settings
+- Safelist patterns for dynamic classes
+- Dark mode support
+
+## Migration from Tailwind v3
+
+If you're upgrading from Tailwind v3:
+
+1. Install the new dependencies: `pnpm install`
+2. Remove any `assets/dist/wc.min.css` files
+3. Add the `package.json` file from the latest starter templates
+4. Update your deployment scripts to install it with `pnpm install` (refer to the latest `.github` folder in the starters)
+5. The old `tailwind.config.js` and `postcss.config.js` files are no longer needed
+
+## Development
+
+For module development:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run development server
+hugo server --disableFastRender
 
-```yaml
-build:
-  writeStats: true
+# Build for production
+hugo --minify
 ```

modules/blox-tailwind/assets/css/blox/navbar.css

@@ -41,7 +41,15 @@ input#nav-toggle:checked ~ #nav-menu {
 }
 
 .nav-link {
-  @apply hover:text-primary-700 dark:hover:text-primary-300 dark:text-white block p-3 font-semibold transition lg:px-2 lg:py-3;
+  @apply dark:text-white block p-3 font-semibold transition lg:px-2 lg:py-3;
+}
+
+.nav-link:hover {
+  color: rgb(var(--color-primary-700));
+}
+
+.dark .nav-link:hover {
+  color: rgb(var(--color-primary-300));
 }
 
 .nav-dropdown {
@@ -63,9 +71,17 @@ input#nav-toggle:checked ~ #nav-menu {
 }
 
 .nav-dropdown-item {
-  @apply px-4  [&:not(:last-child)]:mb-2 dark:hover:bg-primary-500;
+  @apply px-4  [&:not(:last-child)]:mb-2;
+}
+
+.dark .nav-dropdown-item:hover {
+  background-color: rgb(var(--color-primary-500));
 }
 
 .nav-dropdown-link {
-  @apply hover:text-primary-700 dark:text-white  dark:hover:text-white block py-1 font-semibold transition;
+  @apply dark:text-white  dark:hover:text-white block py-1 font-semibold transition;
+}
+
+.nav-dropdown-link:hover {
+  color: rgb(var(--color-primary-700));
 }

modules/blox-tailwind/assets/css/chroma.css

@@ -5,5 +5,12 @@
 /* Requires relative position for Code Copy button */
 .prose .chroma,
 .prose pre {
-  @apply relative rounded-md text-neutral-700 bg-neutral-50 dark:bg-slate-700 dark:text-white;
+  @apply relative rounded-md dark:bg-slate-700 dark:text-white;
+  color: rgb(var(--color-neutral-700));
+  background-color: rgb(var(--color-neutral-50));
+}
+
+.dark .prose .chroma,
+.dark .prose pre {
+  color: white;
 }