valknar/v1.pivoine.art
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: claude and readme

Browse Source
This commit is contained in:
Sebastian Krüger
2025-10-25 13:42:46 +02:00
parent 8c19cf9367
commit df7a363c4f
3 changed files with 316 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
CLAUDE.md Normal file
View File

@@ -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`)

158
README.md Normal file
View File

@@ -0,0 +1,158 @@
# ⚔️ Valknar's Digital Hall ⚔️
<div align="center">
![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/)
</div>
---
## 🗡️ 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.
---
<div align="center">
**⚔️ 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."*
</div>

4
_config.yml
View File

@@ -211,10 +211,6 @@ pivoine:
sound: true sound: true
umami:
script: https://umami.pivoine.art/script.js
id: 26158eb8-e0ae-4985-aa91-2f4a652f8ccb
# ⚡️ DANGER ZONE ⚡️ # ⚡️ DANGER ZONE ⚡️
# ---------------- # ----------------
# This is an _experimental_ feature. # This is an _experimental_ feature.