docs: claude and readme
This commit is contained in:
158
CLAUDE.md
Normal file
158
CLAUDE.md
Normal 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
158
README.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# ⚔️ Valknar's Digital Hall ⚔️
|
||||
|
||||
<div align="center">
|
||||
|
||||
|
||||
|
||||
### *Where Code Meets Art in the Digital Fjords*
|
||||
|
||||
[](https://pivoine.art)
|
||||
[](https://github.com/valknarogg/pivoine.art)
|
||||
[](https://jekyllrb.com/)
|
||||
[](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*
|
||||
|
||||
[](https://twitter.com/bordeaux1981)
|
||||
[](https://github.com/valknarogg)
|
||||
|
||||
*"The wise warrior codes not with brute force, but with elegant solutions."*
|
||||
|
||||
</div>
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user