117 lines
6.5 KiB
Markdown
117 lines
6.5 KiB
Markdown
# 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 high-performance native Node runtime.
|
|
- **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
|
|
├── server.js # Native Node static web server & clean-URL router
|
|
├── Dockerfile # Node container definition (built & served via npm)
|
|
├── docker-compose.yml # Container orchestration (web gateway)
|
|
└── 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
|
|
```
|