mirror of
https://github.com/tiennm99/HugoBlox-kit.git
synced 2026-10-12 16:15:12 +00:00
George Cushen
b67f09b8fd
First-class image gallery block. Two layouts ship today - grid (uniform tiles, configurable columns 1-6, aspect-ratio presets) and masonry (CSS-columns Pinterest packing). Click-to-zoom lightbox built in Preact, portalled to <body> so it escapes the section's `isolation: isolate` stacking context; keyboard navigation (← → Esc), touch swipe, and body scroll-lock included. Two source modes: explicit items[] for curated galleries with per-image captions/credits/links, or album: <folder> for drop-in folder loading sorted by filename. Remote URLs (Unsplash/Pexels/CDNs) are passed through unprocessed; local images get the full responsive variants + inline base64 LQIP placeholder for instant first-paint over the eventual sharp image. Captions, titles, and credits are rendered through Hugo's RenderString at build time (display: inline) - users get full Markdown (bold/italic/ code/links) in any of those fields with zero JS markdown parser. Alt text falls back to plainified caption → humanised filename so screen readers always have something useful. Caption positions: below (default - accessibility-first), overlay (magazine gradient), hover (clean grid reveal), none (lightbox-only). Block-scoped CSS in the co-located style.css is picked up by the existing block-CSS auto-discovery. Test site: two demos under home.yaml (curated grid + auto-loaded masonry) with 9 sample Picsum images stored under test/assets/media/albums/gallery/ at varied aspect ratios.
Hugo Blox (core)
The Hugo Blox web framework powered by Tailwind CSS v4 with Hugo's native integration for styling components with Tailwind v4.
Requirements
- Hugo v0.148.2+ (Extended Edition)
- Node.js v20+
- pnpm (see
packageManagerfield in package.json)
Quick Start
1. Install Dependencies
pnpm install
2. Run Development Server
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.TailwindCSSfunction - 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:
- Install the new dependencies:
pnpm install - Remove any
assets/dist/wc.min.cssfiles - Add the
package.jsonfile from the latest templates - Update your deployment scripts to install it with
pnpm install(refer to the latest.githubfolder in the templates) - The old
tailwind.config.jsandpostcss.config.jsfiles are no longer needed
Development
For module development:
# Install dependencies
pnpm install
# Run development server
hugo server --disableFastRender
# Build for production
hugo --minify
Vendor Libraries
The module includes several third-party vendor libraries that are distributed with the module. These are copied from node_modules to the assets/dist/lib directory during the build process.
To update the vendor libraries:
# Update vendor libraries to the latest versions and rebuild
pnpm vendor:update-and-build
# Just rebuild vendor libraries without updating versions
pnpm vendor:libs
The following libraries are included:
- mermaid (diagrams)
- plotly.js (interactive charts)
- katex (math rendering)
- markmap-autoloader (mind maps)
- alpinejs (interactivity)
- preact (interactive components)