From df7a363c4f520a257e233cc9a9b17670944eed6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Kr=C3=BCger?= Date: Sat, 25 Oct 2025 13:42:46 +0200 Subject: [PATCH] docs: claude and readme --- CLAUDE.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++ _config.yml | 4 -- 3 files changed, 316 insertions(+), 4 deletions(-) create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..82b3d44 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,158 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +This is a Jekyll-based blog/portfolio site built with a custom theme called "pivoine". The site combines Ruby (Jekyll) for static site generation with a modern JavaScript/TypeScript build system using webpack and pnpm workspaces. + +## Build & Development Commands + +### Jekyll (Ruby) Commands +```bash +# Install Ruby dependencies +bundle install + +# Serve the site locally (development mode) +bundle exec jekyll serve + +# Build the site with LSI (latent semantic indexing) for related posts +bundle exec jekyll build --lsi + +# Note: The site uses KaTeX for math rendering which requires Node.js runtime +``` + +### JavaScript/CSS Build Commands +```bash +# Install all dependencies (including workspace packages) +pnpm install + +# Build everything (JS + CSS + scripts) +pnpm run build + +# Build only JavaScript (modern + legacy bundles) +pnpm run build:js + +# Build only CSS +pnpm run build:css + +# Build workspace dependencies first, then main project +pnpm run build:all + +# Development mode with auto-rebuild +pnpm run dev +# or +pnpm run watch + +# Watch JS only +pnpm run watch:js + +# Watch CSS only +pnpm run watch:css + +# Format JavaScript code +pnpm run format + +# Clean built JS files +pnpm run clean +``` + +## Architecture + +### Monorepo Structure +The project uses pnpm workspaces with local packages under `packages/`: +- `packages/hydecorp/component` - Base web component library +- `packages/hydecorp/drawer` - Drawer component +- `packages/hydecorp/push-state` - Push state navigation +- `packages/honeymachine/search` - Search functionality + +These workspace packages are referenced with `workspace:*` protocol in package.json. + +### JavaScript Build System +The webpack configuration (`webpack.config.js`) creates **two bundles**: +1. **Modern bundle** (`pivoine-{version}.js`) - Targets ES modules-compatible browsers +2. **Legacy bundle** (`LEGACY-pivoine-{version}.js`) - Targets IE11+ with full polyfills + +Entry point: `_js/src/entry.js` + +JavaScript source files in `_js/src/` include: +- `common.js` - Shared utilities +- `drawer.js` - Drawer navigation +- `push-state.js` - SPA-like navigation +- `search.js` - Search integration +- `dark-mode.js` - Theme switching +- `sound.js` - Sound effects +- `lightbox.js` - Image lightbox +- `clap-button.js` - GetClaps integration + +### CSS Build System +CSS is built via `.scripts/build-css.js` which processes SCSS files from `_sass/`: +- Main entry points: `html.scss`, `my-style.scss`, `my-inline.scss` +- Uses inline/link comments to control how CSS is included +- Custom variables in `_sass/my-variables.scss` +- Theme SCSS in `_sass/pivoine/` and `_sass/pooleparty/` + +### Jekyll Structure +- `_config.yml` - Main Jekyll configuration with pivoine theme settings +- `_layouts/` - Page templates (base, post, page, blog, etc.) +- `_includes/` - Reusable HTML partials +- `_posts/` - Blog posts organized by category folders (devilish, palina, odinsland, souls, sketches, music) +- `_pages/` - Static pages +- `_data/` - YAML data files (authors, strings, variables, social, countries, sounds) +- `_sass/` - SCSS stylesheets + +### Content Organization +Posts are organized into featured categories defined in `_config.yml`: +- Palina +- Odinsland +- Devilish +- Souls +- Sketches +- Music + +Each post's URL follows the pattern: `/:categories/:slug` + +### Key Configuration Details +- **Math rendering**: Uses `kramdown-math-katex` (requires Node.js runtime) +- **Search**: Disabled in development, enabled in production via `JEKYLL_ENV=production` +- **Dark mode**: Dynamic based on OS settings with manual toggle +- **Pagination**: 5 posts per page using jekyll-paginate-v2 +- **Analytics**: Umami integration configured +- **Related posts**: LSI-based (use `--lsi` flag when building) + +## Development Workflow + +1. **Initial setup**: + ```bash + bundle install + pnpm install + pnpm run build:all + ``` + +2. **Development**: + ```bash + # Terminal 1: Watch and rebuild JS/CSS + pnpm run dev + + # Terminal 2: Run Jekyll server + bundle exec jekyll serve + ``` + +3. **Production build**: + ```bash + pnpm run build:all + JEKYLL_ENV=production bundle exec jekyll build --lsi + ``` + +## Deployment + +The site deploys to GitHub Pages via `.github/workflows/jekyll-gh-pages.yml`. The workflow builds both the JavaScript assets and the Jekyll site, then deploys to `pivoine.art` (configured via CNAME). + +## Important Notes + +- The site uses Node.js version specified in `.nvmrc` +- JavaScript builds create versioned filenames based on package.json version +- Some files are auto-generated (look for "AUTOGENERATED" headers) +- Custom scripts in `.scripts/` directory handle specialized build tasks +- Prettier is configured for JS formatting (`.prettierrc`) +- RuboCop is configured for Ruby linting (`.rubocop.yml`) diff --git a/README.md b/README.md new file mode 100644 index 0000000..e65c087 --- /dev/null +++ b/README.md @@ -0,0 +1,158 @@ +# ⚔️ Valknar's Digital Hall ⚔️ + +
+ +![Falcon Swoop](https://media2.giphy.com/media/v1.Y2lkPTc5MGI3NjExdXJnNWh1Zmd3MGdjZno3aHkzeXVkeXdrbmlqMmcwZTczZWYyM290bSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/AD57MmRuoSype48CXD/giphy.gif) + +### *Where Code Meets Art in the Digital Fjords* + +[![Website](https://img.shields.io/website?url=https%3A%2F%2Fpivoine.art&style=for-the-badge&logo=safari&logoColor=white)](https://pivoine.art) +[![GitHub](https://img.shields.io/badge/GitHub-valknarogg-181717?style=for-the-badge&logo=github)](https://github.com/valknarogg/pivoine.art) +[![Jekyll](https://img.shields.io/badge/Jekyll-4.4-CC0000?style=for-the-badge&logo=jekyll&logoColor=white)](https://jekyllrb.com/) +[![Node](https://img.shields.io/badge/Node.js->=11-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/) + +
+ +--- + +## 🗡️ The Saga Begins + +Welcome, traveler, to **pivoine.art** — the digital longship of **Valknar**, where the ancient spirit of the North meets modern craftsmanship. This is not merely a website; it is a **mead hall** of creativity, a **forge** of code, and a **gallery** of artistic expression. + +Here you'll find tales of: +- 🎨 **Art** — From the Devilish depths to the Souls of imagination +- 💻 **Code** — Crafted with the precision of a master blacksmith +- 🎵 **Music** — Echoes from distant realms +- ✍️ **Stories** — Chronicles from Odinsland, Palina, and beyond + +## ⚡ Features of the Hall + +- **🌙 Dark Mode** — For those who prefer the shadows of Niflheim +- **🔍 Intelligent Search** — Find your path through the archives +- **🎭 Interactive Gallery** — Lightbox views worthy of Valhalla +- **🎵 Sound Effects** — Immersive audio for the brave +- **📱 Responsive Design** — Accessible across all devices, from desktop ravens to mobile drakkars +- **⚡ Modern & Legacy Support** — Built with dual bundles for ancient (IE11+) and modern browsers + +## 🏰 Architecture of the Fortress + +This digital stronghold is built upon: + +- **[Jekyll](https://jekyllrb.com/)** — The Ruby-forged static site generator +- **[Pivoine Theme](https://hydecorp.github.io/hydejack/)** — A customized theme as beautiful as the Northern Lights +- **Webpack** — Bundling JavaScript with the strength of Thor's hammer +- **pnpm Workspaces** — Monorepo organization worthy of a jarl +- **KaTeX** — Mathematical runes rendered with precision +- **Web Components** — Modern browser magic using Lit + +### The Tech Stack Runestones + +``` +Frontend: TypeScript, Lit, RxJS, Web Components +Backend: Jekyll (Ruby), Liquid Templates +Styling: SCSS, Bootstrap-based Framework +Build: Webpack, pnpm, Babel +Deploy: GitHub Pages, GitHub Actions +``` + +## 🛡️ Getting Started + +### Prerequisites + +Before you embark on this journey, ensure you have: + +- **Ruby** (with Bundler) — For Jekyll's ancient magic +- **Node.js** (≥11) — For JavaScript sorcery +- **pnpm** — The swift package manager + +### Summoning the Site + +```bash +# Clone the longship +git clone https://github.com/valknarogg/pivoine.art.git +cd pivoine.art + +# Gather the Ruby provisions +bundle install + +# Gather the JavaScript provisions +pnpm install + +# Forge the JavaScript and CSS artifacts +pnpm run build:all + +# Raise the sails (development server) +bundle exec jekyll serve +``` + +For auto-rebuilding during development: +```bash +# Terminal 1: Watch and rebuild assets +pnpm run dev + +# Terminal 2: Serve the site +bundle exec jekyll serve +``` + +## 🔨 Crafting Commands + +| Command | Purpose | +|---------|---------| +| `pnpm run build` | Build all JavaScript and CSS | +| `pnpm run build:js` | Build JavaScript bundles (modern + legacy) | +| `pnpm run build:css` | Build SCSS stylesheets | +| `pnpm run dev` | Watch mode for development | +| `pnpm run format` | Format JavaScript with Prettier | +| `bundle exec jekyll serve` | Serve site locally | +| `bundle exec jekyll build --lsi` | Build with related posts (LSI) | + +## 📚 Content Realms + +The chronicles are organized into sacred categories: + +- **🎨 Palina** — Artistic visions +- **⚔️ Odinsland** — Nordic-inspired works +- **😈 Devilish** — Dark and provocative art +- **👻 Souls** — Spiritual explorations +- **✏️ Sketches** — Raw creativity +- **🎵 Music** — Sonic journeys + +## 🚀 Deployment + +The site automatically deploys to [pivoine.art](https://pivoine.art) via GitHub Actions when changes are pushed to the main branch. The workflow builds both JavaScript assets and the Jekyll site, then publishes to GitHub Pages. + +## 🎨 Customization + +- **Theme Variables**: Edit `_sass/my-variables.scss` +- **Custom Styles**: Modify `_sass/my-style.scss` +- **Configuration**: Update `_config.yml` +- **JavaScript**: Source files in `_js/src/` + +## 🌐 Live Site + +**Visit the hall:** [https://pivoine.art](https://pivoine.art) + +Experience the fusion of code and creativity, where every pixel is placed with purpose and every line of code tells a story. + +## 📜 License + +© 2025 Valknar. All rights reserved. + +## 🦅 The Falcon's Message + +Like the falcon that swoops with precision and grace, this site is crafted with attention to detail and a commitment to excellence. May your journey through these digital halls be as thrilling as a Viking raid and as enlightening as the runes of old. + +--- + +
+ +**⚔️ Crafted by Valknar ⚔️** + +*Coding, Art, and Life* + +[![Twitter](https://img.shields.io/badge/Twitter-@bordeaux1981-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/bordeaux1981) +[![GitHub](https://img.shields.io/badge/GitHub-valknarogg-181717?style=for-the-badge&logo=github)](https://github.com/valknarogg) + +*"The wise warrior codes not with brute force, but with elegant solutions."* + +
diff --git a/_config.yml b/_config.yml index e166850..56c499f 100644 --- a/_config.yml +++ b/_config.yml @@ -211,10 +211,6 @@ pivoine: sound: true - umami: - script: https://umami.pivoine.art/script.js - id: 26158eb8-e0ae-4985-aa91-2f4a652f8ccb - # ⚡️ DANGER ZONE ⚡️ # ---------------- # This is an _experimental_ feature.