feat: implement dynamic Eleventy tiling blog, modular CSS, and agent customizations

- Add project foundation README.md and root AGENTS.md for pair programming - Configure .agents/ rules and skills for Eleventy tiling and Obsidian publishing - Decompose monolithic styles into modular tokens, reset, layout, and component CSS - Implement Nunjucks layout inheritance (base.njk, post.njk, page.njk) and reusable partials - Configure Eleventy 3 with markdown-it-anchor, syntax highlighting, and dynamic collections - Migrate sample prototypes into dynamic dispatches lander, gateway, and Markdown posts - Add multi-stage Dockerfile and clean-URL nginx.conf for production serving
2026-09-13 00:49:27 -05:00
parent c0f67e75a3
commit d8fb8a3699
37 changed files with 4361 additions and 7 deletions
@@ -0,0 +1,115 @@
+# River Rooks | Technical Publication & Systems Architecture Blog
+
+> Developer-centric, high-signal, low-noise personal technical blog and homelab documentation site.
+
+Inspired by native terminal environments, modal text editors (Zed, Ghostty), and tiling window managers, this site prioritizes raw performance, keyboard navigability, information density, and structured craftsmanship over generic marketing aesthetics.
+
+---
+
+## 1. Architectural Vision & Pillars
+
+### 1.1 Static Generation via Eleventy (11ty)
+- **Engine:** Fast, pre-rendered static HTML and minimal client-side runtime using **Eleventy** and **Nunjucks (`.njk`)** templates.
+- **Performance:** Instant time-to-first-byte (TTFB), zero client-side framework bloat, and pure static asset delivery via Alpine Nginx.
+- **Syntax Highlighting & Code Blocks:** Terminal-styled code blocks with title bars displaying filenames, language tags, and high-contrast monospace code.
+
+### 1.2 Dynamic Obsidian Publishing Pipeline
+- **Seamless Authoring:** Author and edit technical dispatches, CTF write-ups, and homelab notes directly inside an **Obsidian** vault.
+- **Custom Ingestion API:** A dedicated server-side endpoint (`POST /api/posts`) accepting markdown payloads and assets, paired with a custom Obsidian plugin for one-click publishing.
+- **LiveSync Integration:** Architectural support for syncing notes from a self-hosted Obsidian LiveSync (CouchDB) instance.
+- **Content Normalization:** Translates Obsidian wikilinks (`[[slug|Title]]`), callouts (`> [!NOTE]`), and asset references into standard web formats during ingestion and build time.
+
+### 1.3 Strict CSS Isolation & Reusable Templating
+- **No Monolithic Inlines:** Replaces repetitive inline `<style>` tags with a modular CSS token and component architecture.
+- **Design Tokens:** Centralized CSS custom properties (`--bg-canvas`, `--bg-surface`, `--border-color`, `--accent-cyan`, etc.) for consistent dark-mode native styling.
+- **DRY Layouts & Partials:** Reusable Nunjucks components for global navigation (`global-bar`), hero tiles (`hero-tile`), split cards, and article workspace layouts (`article-workspace-grid`).
+
+### 1.4 AI Pair Architect & Pedagogical Explainer
+- **Interactive Learning:** The workspace includes customized Antigravity agent configurations (`.agents/` and `AGENTS.md`) that pair-program with the author, architecting solutions while clearly explaining *how* and *why* code is built.
+
+---
+
+## 2. Strict Design Specification
+
+Adhering to the principles in [`sample-designs/design-specification.md`](./sample-designs/design-specification.md):
+
+| Rule | Constraint |
+| :--- | :--- |
+| **Color Scheme** | Dark-mode native only. Canvas: `#0d0f12`, Surface: `#121417`, Elevated: `#1c1f26`, Borders: `#2b303b`. |
+| **Accents** | High-signal terminal accents used sparingly: Cyan (`#00f0ff`), Green (`#00e676`), Amber (`#ffb700`). |
+| **Borders & Radius** | Crisp 1px solid borders. Zero to 4px maximum border-radius (sharp corners preferred). |
+| **Strict Anti-Patterns** | **NO** glassmorphism (`backdrop-filter`), **NO** drop shadows or glows, **NO** gradients, **NO** spring animations. |
+| **Typography** | Monospace for UI & code (`IBM Plex Mono`, `JetBrains Mono`); clean sans-serif for body prose (`Inter`). |
+| **Interactivity** | Instant binary hover snaps (no slow fade transitions); high-contrast focus outlines for keyboard navigation. |
+
+---
+
+## 3. Project Directory Map
+
+```text
+.
+├── .agents/                        # Antigravity agent configurations & customizations
+│   ├── rules/
+│   │   └── blog-system.md          # Architectural constraints, CSS/template isolation & explainer mode
+│   └── skills/
+│       ├── eleventy-tiling-blog/   # Runbook & recipes for Eleventy builds and component extraction
+│       └── obsidian-sync/          # Runbook & API contracts for Obsidian publishing & plugin sync
+├── sample-designs/                 # Canonical HTML/CSS prototypes & design specification
+│   ├── article-tiling-firmware.html
+│   ├── blog-tiling-lead.html
+│   ├── design-specification.md
+│   └── service-gateway-tiling.html
+├── src/                            # Eleventy source directory (scaffolded in Phase 2)
+│   ├── _data/                      # Global site metadata, navigation, telemetry data
+│   ├── _includes/
+│   │   ├── layouts/                # Base, post, and page templates
+│   │   └── partials/               # Global bar, hero tile, card, code box, sidebar
+│   ├── assets/
+│   │   ├── css/                    # Modular CSS (tokens, reset, layout, components)
+│   │   └── fonts/                  # Self-hosted monospace & prose webfonts
+│   └── posts/                      # Markdown content ingested from Obsidian
+├── .eleventy.js                    # Eleventy configuration, markdown-it plugins, and shortcodes
+├── package.json                    # Project dependencies & build scripts
+├── Dockerfile                      # Alpine Nginx container definition
+├── docker-compose.yml              # Multi-container orchestration (web + ingestion API)
+└── AGENTS.md                       # Project-level agent instructions & pair programming guide
+```
+
+---
+
+## 4. Development & Build Roadmap
+
+- [x] **Phase 1: Foundation & Agent Customizations**
+  - Establish `README.md` architectural blueprint.
+  - Setup `.agents/` workspace rules, skills, and root `AGENTS.md`.
+- [ ] **Phase 2: Eleventy Scaffolding & Modularization**
+  - Initialize Node/npm environment and configure `.eleventy.js`.
+  - Extract design tokens, layout styles, and components into `src/assets/css/`.
+  - Build reusable Nunjucks layouts and partials modeled on `sample-designs/`.
+- [ ] **Phase 3: Dynamic Obsidian Ingestion & Plugin**
+  - Implement the server-side note ingestion endpoint (`POST /api/posts`).
+  - Develop the custom Obsidian plugin for publishing notes and frontmatter.
+  - Integrate wikilink and callout transformation filters.
+- [ ] **Phase 4: Containerization & Deployment**
+  - Verify static build outputs in `_site/`.
+  - Update Dockerfile and `docker-compose.yml` for unified production serving.
+
+---
+
+## 5. Development Setup
+
+*(To be initialized during Phase 2)*
+
+```bash
+# Install dependencies
+npm install
+
+# Start Eleventy local development server with hot-reload
+npm run dev
+
+# Compile static assets for production
+npm run build
+
+# Run via Docker Compose
+docker compose up --build
+```