venus/blog
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: venus/blog:c8cd5fd0d95ed5c13edb42cb885bd2b5a3d089b2
Branches Tags
venus/blog:master venus/blog:dev venus/blog:server venus/blog:sample-selection
..
compare: venus/blog:server
Branches Tags
venus/blog:master venus/blog:dev venus/blog:server venus/blog:sample-selection
5 Commits
c8cd5fd0d9 .. server
Author SHA1 Message Date
venus 2bf5e83964 updated sample compose file to reflect zero downtime deployment on the actual compose file 2026-09-15 00:33:58 -05:00
venus d6c5ed1d3b feat: zero downtime deployment script unlocked 2026-09-15 00:31:56 -05:00
venus 528c302c74 updated docker update script with a bit more verbosity 2026-09-14 23:33:55 -05:00
venus 66c4e89732 feat: script to rebuild docker from latest image 2026-09-14 01:35:30 -05:00
venus 60f77838a0 updated server side infra 2026-09-13 21:28:18 -05:00
75 changed files with 54 additions and 10134 deletions
Expand all files Collapse all files
.agents/rules/blog-system.md
-91
View File
@@ -1,91 +0,0 @@
# Technical Blog System Rules & Architecture Directives
## 1. Core Invariant: User Content Sovereignty (Highest Priority)
1. **User Edits Are Absolute Ground Truth:**
- The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
- They strictly take precedence over any background content description, sample design mockup (`sample-designs/*`), skill instructions, or default boilerplate.
2. **Strict Prohibition on Unsolicited Rewriting or Renaming:**
- You must **NEVER** revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
- Do not reintroduce removed text or names from prior mockups or commits.
3. **Mandatory Clarification Gate:**
- If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must **NOT** unilaterally modify it.
- You must ask the user for specific clarification before altering any user-authored writing or naming.
4. **Sample Designs Are Layout References Only:**
- Files in `sample-designs/` serve solely as visual, CSS, and structural layout references.
- Never extract or re-inject titles, domain names, service labels, or technical copy from `sample-designs/` into active templates or site data without explicit instruction.
---
## 2. Pedagogical Explanations (Interactive Learning)
1. **Explain the Code:** Whenever creating or refactoring code (Eleventy configuration, Nunjucks templates, CSS modules, build scripts), provide a clear, educational breakdown.
2. **Break Down Key Concepts:** Explain *why* a particular Eleventy filter, Nunjucks tag, or CSS variable structure was used so the user learns the foundational concepts.
3. **No Magic:** Avoid opaque or overly clever abstractions; prioritize readable, idiomatic code with commentary explaining tricky points.
---
## 3. CSS Architecture & Isolation
1. **Zero Monolithic Inlines:** Do not inject raw `<style>` blocks into HTML templates.
2. **Modular File Structure:**
- Put global tokens in `src/assets/css/tokens.css`.
- Put reset and base typography in `src/assets/css/reset.css`.
- Put layout structures (tiling layout, split grids) in `src/assets/css/layout.css`.
- Put scoped component styles in `src/assets/css/components/<component-name>.css`.
3. **Design System Token Integrity:** Always use CSS custom properties defined in `tokens.css`:
- Canvas: `var(--bg-canvas)` (`#0d0f12`)
- Surface: `var(--bg-surface)` (`#121417`)
- Elevated: `var(--bg-elevated)` (`#1c1f26`)
- Borders: `var(--border-color)` (`#2b303b`)
- Text: `var(--text-primary)` (`#e0e6f0`), `var(--text-muted)` (`#8a95a5`)
- Accents: `var(--accent-cyan)` (`#00f0ff`), `var(--accent-green)` (`#00e676`), `var(--accent-amber)` (`#ffb700`)
4. **Hard Aesthetic Constraints:**
- No glassmorphism (`backdrop-filter`).
- No box-shadows or glows.
- No linear/radial gradients.
- Border radius strictly bounded between `0px` and `4px`.
- Transition durations set to `none` or `0s` for instant snap responses on hover.
---
## 4. Templating Guidelines (Eleventy + Nunjucks)
1. **Layout Hierarchy:**
- Root template: `src/_includes/layouts/base.njk` (contains HTML structure, `<head>`, metadata, scripts, stylesheets).
- Content layouts: `src/_includes/layouts/post.njk` (for articles), `src/_includes/layouts/page.njk` (for landing/catalog).
2. **Component Partials:**
- Isolated partials in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `stats-sidebar.njk`, `code-box.njk`, `footer.njk`).
- Pass dynamic data via Nunjucks macros or contextual variables.
---
## 5. Obsidian Content Pipeline
1. **Frontmatter Specification:** Every post ingested from Obsidian must adhere to:
```yaml
title: "Article Title"
date: YYYY-MM-DD
tags: ["#tag1", "#tag2"]
excerpt: "Single paragraph summary"
readingTime: "X MIN READ"
draft: false
hidden: false # optional: true unlists post from public feeds/lists, accessible via direct link only
```
2. **Obsidian Normalization:**
- Wikilinks `[[slug]]` or `[[slug|Label]]` must be transformed into standard web URLs (`/posts/slug/`).
- Callout blocks (`> [!NOTE]`, `> [!WARNING]`, etc.) must render as terminal-style alert callouts.
- Images must be processed into `src/assets/images/posts/` and linked via standard `<img>` or Markdown image syntax.
---
## 6. Test-Driven Development (TDD) & Adversarial Verification
1. **Strict Pre-Implementation Testing (Tests Before Functional Code):**
- Test cases MUST ALWAYS be written in `test/*.test.js` before writing or modifying any functional code (filters, templates, server routes, ingestion pipeline, data loaders, scripts).
- Never implement or modify functional or production code prior to writing and establishing corresponding automated tests.
2. **Mandatory Adversarial Test Coverage:**
- Standard behavior for any functional change MUST ALWAYS include adversarial testing specifically designed to stress assumptions and break the system:
- **Data & Configuration:** Test that missing required environment variables (e.g. `SITE_DOMAIN`) throw fatal errors.
- **Filters & Logic:** Test edge cases: empty strings, undefined/null values, unexpected types, single-word inputs, massive word counts, non-date objects.
- **Security & Integrity:** Test path traversals, malformed JSON, unauthorized tokens, malicious payloads.
- **Content Schemas:** Validate all Markdown files in `src/posts/` against frontmatter schemas.
- **Design Spec Compliance:** Automate regex/AST assertions on `src/assets/css/` ensuring zero violations of the "Do Not Use" list (`backdrop-filter`, `box-shadow`, `text-shadow`, gradients, floaty transitions).
- **Link & Anchor Integrity:** Verify that every compiled page has zero broken internal links and that all Table of Contents anchor links resolve to valid heading IDs.
3. **Pre-Presentation Verification Gate:**
- Before presenting the final output to the user, run `npm test`.
- All test cases must pass before presenting the final output. Presenting unverified output or code with failing tests is strictly prohibited.
.agents/skills/eleventy-tiling-blog/SKILL.md
-118
View File
@@ -1,118 +0,0 @@
---
name: eleventy-tiling-blog
description: >-
Use this skill when developing, refactoring, or building the Eleventy blog, modularizing CSS into tokens and components, creating Nunjucks layouts and partials from sample designs, or configuring Eleventy build pipelines.
---
# Eleventy Tiling Blog Development Skill
This skill guides the agent in modularizing templates and CSS from `sample-designs/` into a clean, DRY Eleventy (11ty) static publication site.
> [!IMPORTANT]
> **User Content Sovereignty:** Files in `sample-designs/` are layout and CSS references ONLY. Never extract or re-inject titles, service names, or text from `sample-designs/` over user-defined or sanitized content. User-authored text and naming conventions are the highest level of truth.
---
## 1. CSS Modularization Workflow
When extracting CSS from `sample-designs/*.html` into `src/assets/css/`:
1. **Tokens (`src/assets/css/tokens.css`):**
Extract all `:root` custom properties:
```css
:root {
--bg-canvas: #0d0f12;
--bg-surface: #121417;
--bg-elevated: #1c1f26;
--border-color: #2b303b;
--text-primary: #e0e6f0;
--text-muted: #8a95a5;
--accent-cyan: #00f0ff;
--accent-green: #00e676;
--accent-amber: #ffb700;
--accent-red: #ff5252;
--font-mono: 'IBM Plex Mono', monospace;
--font-code: 'JetBrains Mono', monospace;
--font-prose: 'Inter', sans-serif;
}
```
2. **Reset & Base (`src/assets/css/reset.css`):**
- Universal box-sizing reset (`box-sizing: border-box; margin: 0; padding: 0;`).
- Body font defaults, base line-height (`1.6`), instant hover transitions (`transition: none;`).
- Explicit 1px/2px focus ring styling for keyboard accessibility.
3. **Layout Grid (`src/assets/css/layout.css`):**
- `.tiling-layout`: Centered flex column, `max-width: 1120px` to `1160px`.
- `.split-grid`: 2-column or multi-tile layout with rigid gaps (`16px`).
- `.article-workspace-grid`: Left sticky sidebar (`290px`) + main article reading view (`1fr`).
4. **Component Modules (`src/assets/css/components/`):**
- `global-bar.css`: `.global-bar`, `.brand-group`, `.status-indicator`, `.bar-nav`, `.bar-link`.
- `tiles.css`: `.tile`, `.tile-header`, `.tile-title`, `.tile-meta`, `.hero-tile`.
- `code-box.css`: `.terminal-code-box`, `.code-titlebar`, `.code-content`.
- `article.css`: Prose typography capped at `65ch`, inline `<kbd>`, tables, callouts.
---
## 2. Nunjucks (`.njk`) Component Architecture
1. **Layout Inheritance:**
- `src/_includes/layouts/base.njk`:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{{ title }} | {{ site.title or site.name }}</title>
<link rel="stylesheet" href="/assets/css/main.css">
</head>
<body>
<main class="tiling-layout">
{% include "partials/global-bar.njk" %}
{{ content | safe }}
{% include "partials/footer.njk" %}
</main>
</body>
</html>
```
- `src/_includes/layouts/post.njk`:
Extends `layouts/base.njk`, injecting the `.article-workspace-grid` with the table of contents sidebar and article body.
2. **Reusable Partials:**
- `src/_includes/partials/global-bar.njk`
- `src/_includes/partials/hero-tile.njk`
- `src/_includes/partials/post-card.njk`
- `src/_includes/partials/stats-sidebar.njk`
- `src/_includes/partials/code-box.njk`
---
## 3. Explaining Changes to the User
When writing or modifying Eleventy files:
- Explain **how Nunjucks blocks and layout inheritance prevent template duplication**.
- Explain **how CSS custom properties cascade and ensure dark-mode consistency**.
- Point out how the resulting build outputs raw static HTML in `_site/` with zero runtime JavaScript overhead.
---
## 4. Validation & Verification
Always follow the project TDD standard: write automated tests (including adversarial edge cases) in `test/` before modifying functional templates, filters, or configuration. Ensure all test cases pass before presenting the final output.
Run these commands to test and verify builds:
```bash
# Run complete test suite (unit tests, filters, server, design rules, build integrity)
npm test
# Validate Eleventy configuration and build static output
npx @11ty/eleventy --dryrun
# Build to _site directory
npx @11ty/eleventy
# Launch local dev server with auto-refresh
npx @11ty/eleventy --serve
```
.agents/skills/obsidian-sync/SKILL.md
-113
View File
@@ -1,113 +0,0 @@
---
name: obsidian-sync
description: >-
Use this skill when designing, building, or troubleshooting the Obsidian vault publishing integration, the server upload API, note normalization (wikilinks, callouts, frontmatter), or the custom Obsidian plugin.
---
# Obsidian Vault Publishing & Sync Skill
This skill guides the agent in implementing the custom Obsidian plugin and server-side ingestion workflow for publishing blog posts directly from an Obsidian vault.
> [!IMPORTANT]
> **User Content Sovereignty:** User-authored content, post titles, tags, and formatting are the highest level of truth. The sync and normalization pipelines must preserve user-authored text verbatim and never overwrite or mutate user writing without explicit instruction.
---
## 1. System Architecture
```text
+-------------------+ +-----------------------+
| Obsidian Vault | | Blog Server |
| | | |
| [Active Markdown] | POST /api/posts | /api/posts Endpoint |
| + | -------------------> | + |
| Custom Plugin | (Payload: JSON/MD) | Frontmatter Validator |
+-------------------+ | + |
| Wikilink Normalizer |
| + |
+-------------------+ | Write to `src/posts/` |
| Self-Hosted | CouchDB Sync | + |
| LiveSync Server | ===================> | 11ty Build Trigger |
+-------------------+ +-----------------------+
```
---
## 2. Ingestion API Specification
### Endpoint: `POST /api/posts`
- **Headers:**
- `Content-Type: application/json`
- `Authorization: Bearer <API_SECRET>`
- **Request Body:**
```json
{
"slug": "sample-post",
"content": "---\ntitle: \"Sample Post Title\"\ndate: 2026-09-12\ntags: [\"#tag1\"]\n---\n\n## Content...",
"assets": [
{
"filename": "diagram.png",
"data": "<base64-encoded-image>"
}
]
}
```
- **Response:**
- `200 OK`: `{"status": "published", "path": "/posts/sample-post/"}`
- `400 Bad Request`: `{"error": "Missing required frontmatter: title, date"}`
---
## 3. Obsidian Markdown Normalization Rules
1. **Frontmatter Invariants:**
- Must contain `title`, `date`, `tags` (array), and optional `excerpt`, `readingTime`, `draft`, `hidden`.
2. **Wikilinks Translation:**
- `[[article-slug]]` $\rightarrow$ `[article-slug](/posts/article-slug/)`
- `[[article-slug|Custom Label]]` $\rightarrow$ `[Custom Label](/posts/article-slug/)`
3. **Callout Translation:**
- Obsidian callouts:
```markdown
> [!NOTE]
> Informational notice
```
Must be rendered with corresponding terminal alert styling.
4. **Internal Attachments:**
- `![[screenshot.png]]` $\rightarrow$ translated to `![screenshot](/assets/images/posts/screenshot.png)` and written to `src/assets/images/posts/`.
---
## 4. Custom Obsidian Plugin Development
The Obsidian plugin runs inside Obsidian desktop/mobile and interacts with the Obsidian API:
1. Registers a ribbon icon (e.g. `send` or `terminal`) and a command: `Publish Current Note to Blog`.
2. Reads the active file:
```typescript
const activeFile = this.app.workspace.getActiveFile();
const content = await this.app.vault.read(activeFile);
```
3. Parses frontmatter using Obsidian's metadata cache:
```typescript
const cache = this.app.metadataCache.getFileCache(activeFile);
```
4. Sends the HTTP payload to the configured blog server URL with the Bearer token.
5. Displays an Obsidian `Notice('Published successfully to Blog!')`.
---
## 5. Self-Hosted LiveSync Compatibility
If using CouchDB-based self-hosted LiveSync:
- A local watcher or CouchDB change listener daemon can be configured to detect updates to notes marked with `published: true` or in a dedicated `Blog/` folder.
- When an update event fires, the daemon pulls the latest revision from the CouchDB database, runs the normalization pipeline, and saves it to `src/posts/`.
---
## 6. Validation & Verification
Always write automated test cases in `test/ingestion-api.test.js` before modifying or adding any functional synchronization or endpoint code:
- **Mandatory Adversarial Testing:** Include adversarial tests covering unauthorized tokens, invalid/missing frontmatter schemas, path traversals in slugs, and malformed base64 asset payloads.
- **Pre-Presentation Verification:** Run `npm test` and ensure all test cases pass before presenting the final output.
.agents/skills/standards-verification/SKILL.md
-94
View File
@@ -1,94 +0,0 @@
---
name: standards-verification
description: >-
Use this skill sparingly when a new major function or feature has been implemented, when the user explicitly asks to verify standards, or as a debugging tool to analyze code issues. Targets only modified or relevant files via git status/diff and evaluates them against the project standards document.
---
# Standards Verification Skill
This skill performs targeted architectural and stylistic compliance verification for new or modified code in this repository.
> [!IMPORTANT]
> **Invocation Policy:** Call this skill **sparingly and only when needed**.
> **Valid Triggers:**
> 1. A new major function or architectural feature has been implemented.
> 2. The user asks to call it or requests standards verification.
> 3. An error, test failure, or regression has occurred, and you are using this skill as a debugging tool to determine where the code diverges from project standards.
---
## 1. Targeted Inspection Scope (Not the Whole Codebase)
Do **NOT** scan or audit the whole codebase unless specifically requested by the user or strictly necessary for whole-system refactors.
Instead, narrow the scope to targeted sections using Git:
1. **Check Modified Files:**
```bash
git status -s
```
2. **Inspect Exact Changes:**
```bash
git diff HEAD
```
Or for staged changes:
```bash
git diff --staged
```
3. **Identify Changed Sections:**
Focus only on the files, functions, templates, or styles touched in the current task.
---
## 2. Standards Evaluation Workflow
To verify compliance, read the dedicated project standards document:
- Authoritative document: [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md) (or local skill reference: [`references/standards.md`](file:///home/venus/code/blog/.agents/skills/standards-verification/references/standards.md)).
Evaluate the targeted changes against the core standard pillars:
1. **Design System & CSS Rules:**
- Are any anti-patterns present? Check for `backdrop-filter`, `box-shadow`, `text-shadow` (other than `none`), gradients, or transitions with delays/curves.
- Are border radii strictly bounded between `0px` and `4px`?
- Are colors utilizing CSS custom properties from `tokens.css`?
- Is styling modularized without inline `<style>` tags?
2. **Templating & Eleventy Architecture:**
- Does post rendering adhere to layout inheritance (`base.njk` -> `post.njk`)?
- Are collections (`posts`, `tagList`) properly filtered using `isPostPublic`?
- If a post is marked `hidden`, does the layout emit `<meta name="robots" content="noindex, nofollow">`?
3. **Content & Frontmatter Contracts:**
- Are required frontmatter keys (`title`, `date`, `tags`, `excerpt`) valid and conforming to schema length invariants?
- Are wikilinks and Obsidian attachments normalized?
4. **Server & Security Invariants:**
- Does `server.js` preserve security headers (`X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`)?
- Is path traversal protection in place for all file-serving and API endpoints?
5. **Test-Driven Development (TDD) Invariants:**
- Were automated test cases written *before* functional code was modified?
- Are adversarial test cases included (boundary inputs, nulls, invalid configs)?
- Do all tests pass (`npm test`)?
---
## 3. Stylistic & Architectural Reporting
Compile a structured report highlighting:
- **Conformant Highlights:** Key standards cleanly satisfied.
- **Stylistic Issues & Deviations:** Any formatting inconsistencies, unneeded inline styles, or naming anomalies.
- **Remediation Steps:** Concrete, minimal code adjustments to bring the implementation into full compliance.
---
## 4. Debugging with Standards Verification
When using this skill as a debugging tool to troubleshoot broken builds, failed tests, or runtime bugs:
1. **Locate the Error:** Inspect test failure outputs or server logs to isolate the failing component.
2. **Correlate with Standards:** Compare the problematic implementation against [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md).
3. **Explain the Discrepancy:** Specifically identify where the code is out of touch with project standards (e.g. missing input guards for `null`, collections bypassing `isPostPublic`, un-sanitized slug paths).
4. **Suggest Root Cause & Fix:** Suggest why those issues cause an error and provide the targeted fix.
.agents/skills/standards-verification/references/standards.md
-59
View File
@@ -1,59 +0,0 @@
# Technical Blog Project Standards & Architectural Specification
This document is a direct reference for the `standards-verification` skill, mirroring the authoritative project standards defined in [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md).
---
## 1. User Content Sovereignty (Highest Priority)
- User custom writing, post titles, tags, navigation labels, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups.
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
- Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.
---
## 2. Strict Test-Driven Development (TDD) & Adversarial Verification
- **Test-First Invariant:** Automated test cases in `test/*.test.js` MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts). Never write functional code before tests.
- **Mandatory Adversarial Testing:** Standard behavior for every change must include adversarial tests specifically designed to falsify assumptions (missing env vars like `SITE_DOMAIN`, null/undefined/malformed inputs, boundary values, path traversals, design rule violations).
- **Pre-Presentation Verification Gate:** Run `npm test` before presenting the final output to the user. All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.
---
## 3. Design System & CSS Specification
- **Color Palette:** Canvas `#0d0f12`, Surface `#121417`, Elevated `#1c1f26`, Borders `#2b303b`, Text `#e0e6f0`, Accents `#00f0ff` (Cyan), `#00e676` (Green), `#ffb700` (Amber), `#ff5252` (Red).
- **Hard Anti-Patterns:**
- NO glassmorphism (`backdrop-filter`).
- NO drop shadows or glows (`box-shadow`, `text-shadow`).
- NO linear or radial gradients.
- Border-radius capped at `0px` to `4px` maximum.
- Transitions must be instant binary snaps (`none` or `0s`).
- **Typography:** `IBM Plex Mono` / `JetBrains Mono` for UI and code; `Inter` for body prose.
- **CSS Modularity:** Zero inline `<style>` tags. Decompose into `tokens.css`, `reset.css`, `layout.css`, `components/*.css`.
---
## 4. Templating & Eleventy Architecture
- **Layouts & Partials:** Root `layouts/base.njk`, `layouts/post.njk`, `layouts/page.njk`. Isolated partials in `_includes/partials/`.
- **Collection Filtering:** `collections.posts` and `collections.tagList` must filter through `isPostPublic(post)` (excluding `draft: true` and `hidden: true`).
- **Sorting:** Posts sorted via `postComparator` (pinned/featured first, then chronological descending).
- **Hidden Posts:** When `hidden: true`, page compiles to direct link but is excluded from public lists and injects `<meta name="robots" content="noindex, nofollow">`.
---
## 5. Obsidian Content & Frontmatter Contract
- Required frontmatter: `title` (>= 5 chars), `date` or `created` (ISO), `tags` (array), `excerpt` (>= 20 chars).
- Optional: `readingTime`, `draft`, `hidden`, `pinned`, `featured`.
- Obsidian conversions: Wikilinks `[[slug|Label]]` -> `[Label](/posts/slug/)`, attachments `![[image.png]]` -> `![image](/assets/images/posts/image.png)`.
---
## 6. Server & Security Invariants
- `server.js`: Native Node HTTP, zero external runtime dependencies.
- Security headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`.
- Path traversal defense: Sanitize and verify paths remain inside root.
- Healthcheck: `/healthz` returns 200 OK JSON `{ status: "ok", uptime: ... }`.
---
## 7. Defensive Programming & Error Prevention
- Guard against `null`, `undefined`, primitives in all utility functions.
- Docker: `node:22-alpine`, non-root / clean entrypoint script as PID 1.
.agents/skills/standards-verification/scripts/verify.js
-76
View File
@@ -1,76 +0,0 @@
#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import { execSync } from "node:child_process";
console.log("\n[Standards Verification] Running targeted inspection on modified files...\n");
let statusOutput = "";
try {
statusOutput = execSync("git status -s", { encoding: "utf-8" }).trim();
} catch (err) {
console.error("Error executing git status:", err.message);
process.exit(1);
}
if (!statusOutput) {
console.log("✔ Working tree is clean. No changed files to inspect.");
process.exit(0);
}
const lines = statusOutput.split("\n");
const modifiedFiles = lines
.map((line) => line.slice(3).trim())
.filter((f) => fs.existsSync(f) && fs.statSync(f).isFile());
console.log(`Targeting ${modifiedFiles.length} modified file(s):`);
modifiedFiles.forEach((f) => console.log(` - ${f}`));
console.log("");
let issuesFound = 0;
for (const file of modifiedFiles) {
const content = fs.readFileSync(file, "utf-8");
// 1. CSS anti-patterns
if (file.endsWith(".css")) {
if (/backdrop-filter\s*:/i.test(content)) {
console.error(`✖ Violation in ${file}: Glassmorphism (backdrop-filter) is strictly forbidden.`);
issuesFound++;
}
const shadowMatches = content.match(/(box-shadow|text-shadow)\s*:\s*([^;]+);/gi) || [];
for (const match of shadowMatches) {
if (!/(box-shadow|text-shadow)\s*:\s*none\s*;/i.test(match)) {
console.error(`✖ Violation in ${file}: Drop shadows/glows forbidden: '${match}'`);
issuesFound++;
}
}
if (/(linear-gradient|radial-gradient|conic-gradient)/i.test(content)) {
console.error(`✖ Violation in ${file}: Gradients are strictly forbidden.`);
issuesFound++;
}
const radiusMatches = content.match(/border-radius\s*:\s*([^;]+);/gi) || [];
for (const match of radiusMatches) {
const pxMatch = match.match(/(\d+)\s*px/i);
if (pxMatch && parseInt(pxMatch[1], 10) > 4) {
console.error(`✖ Violation in ${file}: Border radius must be <= 4px: '${match}'`);
issuesFound++;
}
}
}
// 2. Monolithic inline styles in templates
if (file.endsWith(".njk") || file.endsWith(".html")) {
if (/<style[^>]*>[\s\S]*?<\/style>/i.test(content)) {
console.error(`✖ Violation in ${file}: Monolithic inline <style> tags are forbidden. Modularize into src/assets/css/`);
issuesFound++;
}
}
}
if (issuesFound > 0) {
console.error(`\n✖ Standards Verification failed: ${issuesFound} issue(s) detected.\n`);
process.exit(1);
} else {
console.log("✔ Targeted standards verification passed with 0 violations.\n");
}
.agents/standards.md
-124
View File
@@ -1,124 +0,0 @@
# Technical Blog Project Standards & Architectural Specification
This document defines the authoritative engineering, design, templating, and security standards for this technical publication codebase. All new implementations, pull requests, refactors, and debugging tasks must conform to these rules.
---
## 1. User Content Sovereignty (Highest Priority)
1. **User Edits Are Absolute Ground Truth:**
- The user's custom writing, post titles, tags, navigation labels, terminology, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups (`sample-designs/*`).
2. **No Unsolicited Modifications:**
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
3. **Mandatory Clarification Gate:**
- Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.
---
## 2. Strict Test-Driven Development (TDD) & Adversarial Verification
1. **Test-First Invariant (Tests Before Code):**
- Automated test cases in `test/*.test.js` MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts).
- Never implement or modify production code prior to establishing tests.
2. **Mandatory Adversarial Testing:**
- Every functional implementation must include adversarial tests designed to actively falsify assumptions:
- Missing or malformed configuration (e.g., unset `SITE_DOMAIN` must throw).
- Corrupt or unexpected inputs (empty strings, `null`, `undefined`, unexpected types, HTML injections, path traversals, giant payloads).
- Boundary values and edge cases.
- Design rule violation assertions (0 instances of forbidden CSS patterns).
- Link and anchor integrity checks.
3. **Pre-Presentation Verification Gate:**
- Before presenting the final output to the user, run `npm test`.
- All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.
---
## 3. Design System & CSS Specification
Strict adherence to `sample-designs/design-specification.md` is mandatory.
### 3.1 Color Palette & Token Variables
All colors must use standard CSS custom properties defined in `src/assets/css/tokens.css`:
- Canvas: `var(--bg-canvas)` (`#0d0f12`)
- Surface: `var(--bg-surface)` (`#121417`)
- Elevated: `var(--bg-elevated)` (`#1c1f26`)
- Borders: `var(--border-color)` (`#2b303b`)
- Text: `var(--text-primary)` (`#e0e6f0`), `var(--text-muted)` (`#8a95a5`)
- Accents: `var(--accent-cyan)` (`#00f0ff`), `var(--accent-green)` (`#00e676`), `var(--accent-amber)` (`#ffb700`), `var(--accent-red)` (`#ff5252`)
### 3.2 Hard Anti-Patterns (Forbidden)
- **NO Glassmorphism:** Never use `backdrop-filter: blur(...)`.
- **NO Drop Shadows or Glows:** `box-shadow: none;` and `text-shadow: none;` only.
- **NO Gradients:** Never use `linear-gradient`, `radial-gradient`, or `conic-gradient`. Flat solid surfaces only.
- **NO Rounded Bubbles:** `border-radius` is strictly capped between `0px` and `4px` maximum.
- **NO Floaty / Delayed Transitions:** Hover and state transitions must be instant binary snaps (`transition: none;` or `transition: 0s;`).
### 3.3 Typography & Modularity
- UI & Code: `IBM Plex Mono`, `JetBrains Mono`.
- Body Prose: `Inter`.
- CSS Modularity: Zero monolithic inline `<style>` tags in HTML. Decompose styles into `tokens.css`, `reset.css`, `layout.css`, and `components/*.css`.
---
## 4. Templating & Eleventy Architecture
1. **Layout Inheritance (Nunjucks):**
- Root layout: `src/_includes/layouts/base.njk`.
- Post layout: `src/_includes/layouts/post.njk`.
- Page layout: `src/_includes/layouts/page.njk`.
- Modular reusable partials in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `stats-sidebar.njk`, `code-box.njk`, `footer.njk`).
2. **Collection Invariants:**
- `collections.posts`: Must filter through `isPostPublic(post)` (excluding both `draft: true` and `hidden: true`) and sort using `postComparator` (prioritizing pinned/featured posts, then chronological descending).
- `collections.tagList`: Must filter through `isPostPublic(post)` so draft or unlisted tags never leak into public category filters.
3. **Hidden / Unlisted Post Contract:**
- When frontmatter specifies `hidden: true`:
- Excluded from public lists, indices, and tag aggregates.
- Static page STILL compiles to `/posts/<slug>/index.html` and is accessible via direct URL.
- Emits `<meta name="robots" content="noindex, nofollow">` in `<head>` to prevent search indexing.
---
## 5. Obsidian Content & Frontmatter Contract
1. **Frontmatter Schema:**
```yaml
title: "Article Title" # Required: string (>= 5 chars)
date: 2026-09-23 # Required: ISO YYYY-MM-DD (or 'created')
tags: ["#tag1", "#tag2"] # Required: non-empty YAML array
excerpt: "Article summary..." # Required: string (>= 20 chars)
readingTime: "5 MIN READ" # Optional: explicit override
draft: false # Optional: boolean
hidden: false # Optional: boolean (share by link only)
pinned: false # Optional: boolean (prioritized to top)
featured: false # Optional: boolean (featured pillar)
```
2. **Obsidian Syntax Normalization:**
- Wikilinks: `[[target-slug|Custom Label]]` $\rightarrow$ `[Custom Label](/posts/target-slug/)`.
- Wikilinks simple: `[[target-slug]]` $\rightarrow$ `[target-slug](/posts/target-slug/)`.
- Attachments: `![[image.png]]` $\rightarrow$ `![image](/assets/images/posts/image.png)`.
- Terminal alert callouts for `> [!NOTE]`, `> [!WARNING]`, etc.
---
## 6. Server & Security Invariants
1. **Native Runtime:**
- `server.js` uses native Node standard library (`node:http`, `node:fs`, `node:path`) with zero external runtime dependencies.
2. **Security Headers on All Responses:**
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `Referrer-Policy: strict-origin-when-cross-origin`
3. **Path Traversal Defense:**
- Sanitize all requested file paths using `path.resolve` and verify the resolved path remains rooted inside the target directory. Block `..` and malicious slug sequences.
4. **Healthcheck Telemetry:**
- `/healthz` and `/health` must respond with HTTP 200 JSON `{ status: "ok", uptime: <seconds> }`.
---
## 7. Defensive Programming & Error Prevention
1. **Input Guarding:**
- Never assume incoming arguments have expected shape. Always guard against `null`, `undefined`, non-objects, and primitive inputs (e.g., `item.data ?? item`).
2. **Clean Container Contracts:**
- Container images must use `node:22-alpine`.
- Dynamic entrypoint (`entrypoint.sh`) must build markdown on boot, handle optional watcher (`WATCH=true`), and execute server as PID 1 (`exec node server.js`).
.gitignore
+1 -3
View File
@@ -5,6 +5,4 @@ _site/
*.log
.env
docker-compose.yml
# Local browser fixtures for document-based development
src/posts/*.md
posts/*
AGENTS.md
-103
View File
@@ -1,103 +0,0 @@
# AGENTS.md: Technical Blog Agent Guidelines
You are the dedicated Senior Pair Architect, Lead Developer, and Pedagogical Coding Mentor for this technical blog.
---
## 1. Core Invariant: User Content Sovereignty (Highest Priority)
1. **User Edits Are Absolute Ground Truth:**
- The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
- They strictly take precedence over any background content description, sample design mockup (`sample-designs/*`), skill instructions, or default boilerplate.
2. **Strict Prohibition on Unsolicited Rewriting or Renaming:**
- You must **NEVER** revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
- Do not reintroduce removed text or names from prior mockups or commits.
3. **Mandatory Clarification Gate:**
- If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must **NOT** unilaterally modify it.
- You must ask the user for specific clarification before altering any user-authored writing or naming.
4. **Sample Designs Are Layout References Only:**
- Files in `sample-designs/` serve solely as visual, CSS, and structural layout references.
- Never extract or re-inject titles, domain names, service labels, or technical copy from `sample-designs/` into active templates or site data without explicit instruction.
---
## 2. Operating Persona & Responsibilities
### 2.1 Senior Pair Architect & Code Author
- Write robust, modular, production-grade code adhering to clean architecture.
- Structure files logically with clear component boundaries, minimal dependencies, and zero code duplication.
- Build static rendering workflows with **Eleventy (11ty)** and **Nunjucks (`.njk`)**.
### 2.2 Interactive Explainer & Teacher (Crucial)
- The user is building this blog to learn web architecture, templating, and CSS engineering.
- **Always explain the code you write**: Whenever creating or editing templates, scripts, or stylesheets, provide concise, high-signal explanations covering:
1. **How it works:** The mechanical flow, syntax, and internal lifecycle (e.g., how Eleventy processes collections, how CSS custom properties cascade).
2. **Why this approach was chosen:** The architectural trade-offs, advantages over alternatives, and best practices.
3. **Core concepts to understand:** Highlight foundational concepts so the user builds deep, transferable mental models.
### 2.3 Strict Design Guardian
Every component, style, and layout change must strictly adhere to [`sample-designs/design-specification.md`](./sample-designs/design-specification.md):
- **Dark Mode Native:** Canvas `#0d0f12`, Surface `#121417`, Elevated `#1c1f26`, Border `#2b303b`, Text `#e0e6f0`, Accents `#00f0ff` (Cyan), `#00e676` (Green), `#ffb700` (Amber).
- **Hard Anti-Patterns:**
- **NO** glassmorphism (`backdrop-filter: blur()`).
- **NO** drop shadows or glows (`box-shadow`, `text-shadow`).
- **NO** gradients (linear or radial).
- **NO** spring animations or floaty delays.
- **NO** rounded bubbles (border-radius capped at 0px to 4px).
- **Interactivity:** Instant binary hover state transitions (no 300ms easing); high-contrast 1px/2px focus outlines for keyboard navigation.
- **Typography:** IBM Plex Mono / JetBrains Mono for UI elements and code blocks; Inter for body prose.
### 2.4 Strict Test-Driven Development (TDD) & Adversarial Verification Mandate
- **Strict Test-First Invariant (Tests Before Code):**
- Test cases MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts).
- Never write or modify functional or production code before the corresponding automated tests are created.
- **Mandatory Adversarial Testing:**
- Standard behavior for any functional change MUST ALWAYS include adversarial testing specifically designed to falsify assumptions and break the implementation:
- Missing or malformed environment variables (e.g., unset `SITE_DOMAIN` must throw).
- Malformed frontmatter (missing required keys, invalid dates, malformed tags, extra/empty fields).
- Edge-case and malicious inputs to filters and functions (empty strings, undefined/null values, unexpected types, HTML injections, path traversals, giant payloads).
- Design rule violations (asserting 0 instances of `backdrop-filter`, `box-shadow`, gradients, or floaty animations).
- Broken internal links, missing assets, and broken TOC anchor tags.
- **Pre-Presentation Verification Gate:**
- Before presenting the final output to the user, the agent MUST run the full test suite (`npm test`).
- All test cases must pass before presenting the final output. Never deliver, present, or claim completion of work if any test case is failing or unverified.
---
## 3. Code Modularity & Isolation Guidelines
### 3.1 CSS Isolation
- **Forbidden:** Monolithic inline `<style>` blocks in HTML or templates.
- **Required Architecture:** All styling must be decomposed into modular files under `src/assets/css/`:
- `tokens.css`: Color variables, typography tokens, border variables, spacing scale.
- `reset.css`: CSS reset, typography baseline, instant transition overrides.
- `layout.css`: `.tiling-layout`, `.split-grid`, `.article-workspace-grid`.
- `components/*.css`: Isolated per-component stylesheets (`global-bar.css`, `tiles.css`, `code-box.css`, `article.css`).
### 3.2 Template Isolation (Nunjucks)
- Use layout inheritance: `base.njk` defines the outer shell and head assets; specialized layouts (`post.njk`, `page.njk`) extend `base.njk`.
- Reusable UI chunks must live in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `code-box.njk`, `stats-sidebar.njk`).
- Use Nunjucks macros or parameters for parameterized UI elements rather than copy-pasting HTML.
---
## 4. Obsidian Content & API Integration
- Treat Markdown posts authored in Obsidian as the single source of truth for blog articles.
- Ingestion pipeline must validate frontmatter schemas:
```yaml
title: "Title of Post"
date: 2026-09-12
tags: ["#tag1", "#tag2"]
excerpt: "Short synopsis of article."
readingTime: "8 MIN READ"
draft: false
hidden: false # optional: true unlists post from public feeds and lists, accessible only via direct link
```
- Support Obsidian syntax conversion:
- Wikilinks `[[my-note|Custom Text]]` $\rightarrow$ `/posts/my-note/`.
- Obsidian callouts `> [!NOTE]` $\rightarrow$ semantic HTML alerts.
- Media/attachments $\rightarrow$ routed to static asset directories.
Dockerfile
-33
View File
@@ -1,33 +0,0 @@
FROM node:22-alpine
WORKDIR /app
# Dynamic build arguments & environment variables
ARG SITE_DOMAIN
ARG SITE_URL
ARG PORT=8080
ENV SITE_DOMAIN=$SITE_DOMAIN
ENV SITE_URL=$SITE_URL
ENV PORT=$PORT
ENV NODE_ENV=production
# Install dependencies
COPY package*.json ./
RUN npm ci
# Copy application source files
COPY . .
RUN chmod +x /app/entrypoint.sh
# Pre-compile baseline static assets
RUN npm run build
# Expose web server port dynamically
EXPOSE ${PORT}
# Native container healthcheck probing IPv4 loopback
HEALTHCHECK --interval=30s --timeout=5s --start-period=3s --retries=3 \
CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 8080) + '/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
# Serve site using dynamic entrypoint
ENTRYPOINT ["/app/entrypoint.sh"]
README.md
-230
View File
@@ -1,230 +0,0 @@
# River Rooks | Technical Publication & Systems Architecture Blog
> Developer-centric, high-signal, low-noise personal technical publication and systems architecture blog.
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. Quickstart: Production Server Deployment
The production deployment uses a **decoupled container architecture**. The server does not need Node.js, git, or build dependencies—it only pulls the prebuilt engine from the registry and mounts a local folder containing your Markdown posts.
### 1.1 Server Directory Structure (`~/docker/blog`)
```text
~/docker/blog/
├── .env # Environment variables (SITE_DOMAIN, etc.)
├── docker-compose.yml # Production container definition
└── posts/ # Your live Markdown articles (.md)
```
### 1.2 Production `docker-compose.yml`
```yaml
services:
web:
image: git.riverrooks.dev/venus/river-rooks-blog:latest
container_name: river_rooks_web
restart: unless-stopped
volumes:
- "./posts:/app/src/posts:ro"
environment:
- "SITE_DOMAIN=${SITE_DOMAIN:?Error: SITE_DOMAIN is not set. Please define SITE_DOMAIN in .env}"
- "SITE_URL=${SITE_URL:-https://${SITE_DOMAIN}}"
- "PORT=${PORT:-8080}"
- "WATCH=${WATCH:-false}"
ports:
- "${HOST_PORT:-${PORT:-8080}}:${PORT:-8080}"
networks:
- backend
labels:
- "traefik.enable=true"
- "traefik.http.routers.blog.rule=Host(`riverrooks.dev`) || Host(`www.riverrooks.dev`)"
- "traefik.http.routers.blog.entrypoints=websecure"
- "traefik.http.routers.blog.tls.certresolver=basic"
- "traefik.http.services.blog.loadbalancer.server.port=8080"
- "traefik.docker.network=backend"
networks:
backend:
external: true
```
### 1.3 Deployment Commands
```bash
# 1. Pull the prebuilt engine from Gitea registry
docker compose pull
# 2. Launch the container
docker compose up -d
# 3. Verify healthcheck status (transitions to healthy in 3-5 seconds)
docker compose ps
```
---
## 2. Local Development & Verification
All templates, styles, and engine code are developed in this repository (`~/code/blog`).
### 2.1 Native Node.js Workflow
```bash
# Install dependencies
npm install
# Run automated test suite (unit tests, filters, server, and docker assertions)
npm test
# Launch Eleventy dev server with hot-reload (binds to http://localhost:8080)
npm run dev
# Compile static assets to _site/
npm run build
# Start the native static server locally
npm start
```
### 2.2 Local Docker Compose Workflow
The local `docker-compose.yml` provides sensible defaults (`localhost`, port 8080, and mounts `./src/posts`):
```bash
# Build and run the local container stack
docker compose up -d --build
# View container logs (Eleventy compilation + server output)
docker compose logs -f
# Stop and clean up
docker compose down
```
### 2.3 Development Standards: Strict TDD & Adversarial Verification
This project enforces a strict test-first development lifecycle and verification standard:
1. **Tests Written Before Functional Code:** Automated test cases in `test/` must always be written before writing or modifying any functional code, filters, templates, server endpoints, or scripts.
2. **Mandatory Adversarial Testing:** Standard behavior for any functional change must always include adversarial test cases (boundary values, malformed/null inputs, unauthorized requests, path traversals, corrupt frontmatter, and design spec violations).
3. **Pre-Presentation Verification Gate:** Every change must be verified by running `npm test`. All test cases must pass before presenting the final output or committing code.
---
## 3. Push & Update Cycles
Because the system separates the **Engine** (templates/code) from the **Content** (markdown notes), updates follow two distinct paths:
### 3.1 Publishing or Editing Articles (Content Workflow)
When you write a new note or edit an existing article:
1. **Add or update the Markdown file** in `posts/` (e.g. `posts/my-new-post.md`):
```yaml
---
title: "My Article Title"
date: 2026-09-14
tags: ["#systems", "#architecture"]
excerpt: "A short synopsis of the article."
hidden: false # (Optional) Set to true to hide from public lists while keeping direct link active
---
# Article Content...
```
2. **Recompile the site:**
```bash
docker compose restart web
```
*Eleventy compiles the mounted markdown in ~150ms and starts serving immediately.*
> [!TIP]
> **Zero-Restart Live Reload:** Set `WATCH=true` in your server's `docker-compose.yml` environment. Eleventy will watch the `posts/` directory in the background. Whenever a note is saved or synced (e.g., from Obsidian), the site automatically updates in memory without running any commands.
### 3.2 Updating Blog Templates, CSS, or Features (Engine Workflow)
When you modify design tokens, Nunjucks templates, server routes, or dependencies:
1. **Develop and verify locally:**
```bash
npm test
```
2. **Build and push the new engine image to the Gitea container registry:**
```bash
# Build the engine image
docker build -t git.riverrooks.dev/venus/river-rooks-blog:latest .
# Push to Gitea
docker push git.riverrooks.dev/venus/river-rooks-blog:latest
```
3. **Update the production server:**
```bash
docker compose pull
docker compose up -d
```
---
## 4. System Architecture & Structure
### 4.1 High-Level Architecture
```text
┌─────────────────────────────────────────────────────────────┐
│ Dev Machine / Workstation │
│ src/ (templates, CSS, config) + Dockerfile + entrypoint.sh │
└──────────────────────────────┬──────────────────────────────┘
│ docker push
▼
┌─────────────────────────────────────────────────────────────┐
│ Gitea Container Registry (git.riverrooks.dev) │
│ image: venus/river-rooks-blog:latest │
└──────────────────────────────┬──────────────────────────────┘
│ docker pull
▼
┌─────────────────────────────────────────────────────────────┐
│ Production Server │
│ │
│ ~/docker/blog/posts/ ──(volume)──> [ river_rooks_web ] │
│ (Live Markdown Notes) ├── entrypoint.sh │
│ ├── 11ty compiles │
│ Traefik (SSL / Proxy) <──────────── └── server.js (:8080) │
└─────────────────────────────────────────────────────────────┘
```
### 4.2 Key Engine Components
- **`entrypoint.sh`**: Dynamic container entrypoint. Compiles mounted markdown notes with Eleventy on boot, starts optional background file watcher, and spawns `server.js` as PID 1 for clean signal handling.
- **`Dockerfile`**: Minimal `node:22-alpine` container with pre-installed dependencies, baseline static pre-compilation, and baked-in `HEALTHCHECK` querying `http://127.0.0.1:8080/healthz`.
- **`server.js`**: Zero-dependency native Node static web server supporting clean directory URLs, MIME caching, security headers, and the `/healthz` telemetry endpoint.
- **`eleventy.config.js`**: Eleventy 3.x configuration, custom collections (`posts`, `tagList`), markdown-it anchor plugins, and custom date/reading-time filters.
### 4.3 Directory Map
```text
.
├── .agents/ # Antigravity agent configurations & rules
├── sample-designs/ # Design specifications & HTML/CSS prototypes
├── src/ # Blog engine source
│ ├── _data/ # Site metadata & navigation
│ ├── _filters/ # Modular Eleventy filters (date, readingTime, headings)
│ ├── _includes/
│ │ ├── layouts/ # Base & post Nunjucks templates
│ │ └── partials/ # Global bar, hero tile, post cards, code box
│ ├── assets/
│ │ └── css/ # Modular CSS (tokens, reset, layout, components)
│ └── posts/ # Default/fallback markdown posts
├── test/ # Automated test suite (node:test)
├── docker-compose.yml # Local development compose file
├── sample-docker-compose.yml # Production-ready compose template
├── Dockerfile # Production container image definition
├── entrypoint.sh # Container startup & compilation entrypoint
├── server.js # Native Node static HTTP server
├── eleventy.config.js # Eleventy configuration
├── package.json # Project scripts & dependencies
└── README.md # Documentation & runbook
```
---
## 5. Strict Design Specification
All UI components and stylesheets strictly follow [`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** | Terminal accents: Cyan (`#00f0ff`), Green (`#00e676`), Amber (`#ffb700`), Red (`#ff5252`). |
| **Borders & Radius** | Crisp 1px solid borders. Zero to 4px maximum border-radius (sharp corners). |
| **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. |
builddocker.sh
-7
View File
@@ -1,7 +0,0 @@
#! /usr/bin/env zsh
echo building docker image and pushing to remote server
docker build -t git.riverrooks.dev/venus/river-rooks-blog:latest /home/venus/code/blog/
docker push git.riverrooks.dev/venus/river-rooks-blog:latest
echo docker image built and pushed, now updating remote server
ssh sol "cd docker/blog && ./docker-update.zsh"
docker-update.zsh
Executable
+36
View File
@@ -0,0 +1,36 @@
#!/usr/bin/env zsh
set -e
echo "pulling latest build image..."
docker compose pull
# Check which service is running
if docker compose ps blog-blue --filter "status=running" -q | grep -q .; then
CURRENT="blog-blue"
TARGET="blog-green"
else
CURRENT="blog-green"
TARGET="blog-blue"
fi
echo "Current: $CURRENT -> deploying Target: $TARGET"
# TODO dont run if 0 instances running
# Scale current deployment to two instances, keeping the old one and adding a running env of the new one
docker compose up -d --no-deps $TARGET
echo "waiting for $TARGET to pass healthcheck..."
# docker ps --filter 'label=com.docker.compose.service=blog' --filter 'health=starting'
until [[ "$(docker inspect --format '{{.State.Health.Status}}' $(docker compose ps -q $TARGET) 2>/dev/null)" == "healthy" ]]; do
sleep 1
done
# Give traefik backend a few seconds to update
sleep 3
echo "Stopping $CURRENT..."
docker compose stop $CURRENT
docker compose rm -f $CURRENT
echo "Zero downtime deployment to $TARGET complete."
# TODO zero downtime deployment
# TODO run on a cron job
eleventy.config.js
-91
View File
@@ -1,91 +0,0 @@
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";
import markdownIt from "markdown-it";
import markdownItAnchor from "markdown-it-anchor";
import { filters } from "./src/_filters/index.js";
import { postComparator, isPostPublic } from "./src/_utils/sort-posts.js";
import { validateLinkedArticles } from "./src/_utils/linked-articles.js";
export default function (eleventyConfig) {
// Build ignored local post fixtures without making them Git-tracked.
eleventyConfig.setUseGitIgnore(false);
// 1. Static Asset Passthrough Copy
eleventyConfig.addPassthroughCopy({ "src/assets": "assets" });
// 2. Syntax Highlighting Plugin
eleventyConfig.addPlugin(syntaxHighlight);
// 3. Markdown-It Library Customization
const markdownOptions = {
html: true,
breaks: false,
linkify: true
};
const markdownLib = markdownIt(markdownOptions).use(markdownItAnchor, {
permalink: markdownItAnchor.permalink.headerLink({
safariReaderFix: true
}),
slugify: (s) =>
s
.trim()
.toLowerCase()
.replace(/[^a-z0-9 -]/g, "")
.replace(/\s+/g, "-")
.replace(/-+/g, "-")
});
eleventyConfig.setLibrary("md", markdownLib);
// 4. Custom Filters (imported from modular src/_filters/index.js)
for (const [name, fn] of Object.entries(filters)) {
eleventyConfig.addFilter(name, fn);
}
// 5. Custom Collections
// Pinned / featured prioritized, chronological blog posts collection (excludes drafts and hidden posts)
eleventyConfig.addCollection("posts", (collectionApi) => {
const allPosts = collectionApi.getFilteredByGlob("src/posts/*.md");
validateLinkedArticles(allPosts);
return allPosts
.filter((post) => isPostPublic(post))
.sort(postComparator);
});
// Dynamic Tag List Collection across all public posts (excludes drafts and hidden posts)
eleventyConfig.addCollection("tagList", (collectionApi) => {
const tagSet = new Set();
collectionApi
.getFilteredByGlob("src/posts/*.md")
.filter((post) => isPostPublic(post))
.forEach((item) => {
if ("tags" in item.data) {
let tags = item.data.tags;
if (typeof tags === "string") tags = [tags];
for (const tag of tags) {
const cleanTag = tag.replace(/^#/, "");
tagSet.add(cleanTag);
}
}
});
return [...tagSet].sort();
});
// 6. Dev Server Options (dynamic port binding)
eleventyConfig.setServerOptions({
port: parseInt(process.env.PORT || "8080", 10)
});
return {
dir: {
input: "src",
includes: "_includes",
data: "_data",
output: "_site"
},
templateFormats: ["njk", "md", "html"],
htmlTemplateEngine: "njk",
markdownTemplateEngine: "njk"
};
}
entrypoint.sh
-25
View File
@@ -1,25 +0,0 @@
#!/bin/sh
# Pass-through mode: if arguments were provided, execute them directly
if [ "$#" -gt 0 ]; then
exec "$@"
fi
# Ensure posts directory data file exists for layout inheritance
if [ ! -f src/posts/posts.json ]; then
echo '{"layout": "layouts/post.njk"}' > src/posts/posts.json
fi
# Build static site from mounted or packaged markdown posts
echo "[blog-engine] Compiling static site with Eleventy..."
npm run build || exit 1
# Optional watch mode for zero-restart live note updates
if [ "${WATCH:-false}" = "true" ]; then
echo "[blog-engine] Starting live watch daemon for markdown changes..."
npx @11ty/eleventy --watch &
fi
# Start production static web server
echo "[blog-engine] Starting static server on port ${PORT:-8080}..."
exec node server.js
package-lock.json
Generated
-1618
View File
File diff suppressed because it is too large Load Diff
package.json
-31
View File
@@ -1,31 +0,0 @@
{
"name": "river-rooks-blog",
"version": "1.0.0",
"description": "Developer-centric personal technical publication and systems architecture blog",
"type": "module",
"main": "eleventy.config.js",
"scripts": {
"dev": "eleventy --serve --watch",
"build": "eleventy",
"serve": "node server.js",
"start": "node server.js",
"test": "node --test 'test/**/*.test.js'",
"clean": "rm -rf _site"
},
"keywords": [
"eleventy",
"blog",
"tiling",
"nunjucks",
"obsidian"
],
"author": "River Rooks",
"license": "MIT",
"dependencies": {
"@11ty/eleventy": "^3.1.6",
"@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2",
"luxon": "^3.5.0",
"markdown-it": "^14.1.0",
"markdown-it-anchor": "^9.2.0"
}
}
sample-designs/article-tiling-firmware.html
-1003
View File
File diff suppressed because it is too large Load Diff
sample-designs/blog-tiling-lead.html
-781
View File
@@ -1,781 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>River Rooks | Blog Lander (Tiling Hero &amp; Feed)</title>
<style>
@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,700;1,400&family=Inter:wght@400;500;700&family=JetBrains+Mono:ital,wght@0,400;0,500;1,400&display=swap');
:root {
--bg-canvas: #0d0f12; /* Deep slate/charcoal canvas */
--bg-surface: #121417; /* Tile surface */
--bg-elevated: #1c1f26; /* Hovered tile surface */
--border-color: #2b303b; /* Crisp 1px solid border */
--text-primary: #e0e6f0; /* Light off-white prose */
--text-muted: #8a95a5; /* Monospace metadata */
--accent-cyan: #00f0ff; /* Primary active accent */
--accent-green: #00e676; /* Operational status indicator */
--accent-amber: #ffb700; /* Warning / highlight accent */
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
background-color: var(--bg-canvas);
color: var(--text-primary);
font-family: 'Inter', sans-serif;
line-height: 1.6;
min-height: 100vh;
display: flex;
flex-direction: column;
align-items: center;
padding: 24px 16px 48px 16px;
}
.tiling-layout {
width: 100%;
max-width: 1120px;
display: flex;
flex-direction: column;
gap: 16px;
}
/* Top Global Status Header Bar (Gateway 3 Style) */
.global-bar {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 10px 18px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.8rem;
flex-wrap: wrap;
gap: 10px;
}
.brand-group {
display: flex;
align-items: center;
gap: 10px;
color: var(--text-primary);
font-weight: 700;
}
.status-indicator {
width: 8px;
height: 8px;
background-color: var(--accent-green);
display: inline-block;
}
.bar-nav {
display: flex;
gap: 14px;
align-items: center;
}
.bar-link {
color: var(--text-muted);
text-decoration: none;
transition: none; /* Instant snap */
}
.bar-link:hover {
color: var(--accent-cyan);
}
.bar-link.active {
color: var(--text-primary);
border-bottom: 1px solid var(--accent-cyan);
}
/* Hero Tile: Section Declaration & Synopsis */
.hero-tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-left: 3px solid var(--accent-cyan);
border-radius: 4px;
padding: 24px 28px;
display: flex;
flex-direction: column;
gap: 12px;
margin-bottom: 16px;
}
.hero-pretitle {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.8rem;
color: var(--accent-cyan);
letter-spacing: 0.06em;
text-transform: uppercase;
}
.hero-main-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 2.1rem;
font-weight: 700;
color: var(--text-primary);
letter-spacing: -0.02em;
line-height: 1.2;
}
.hero-landing-text {
font-size: 0.98rem;
color: var(--text-primary);
line-height: 1.65;
max-width: 82ch;
}
.filter-pills-row {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 8px;
margin-top: 4px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
}
.filter-tag-btn {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
color: var(--text-muted);
padding: 3px 8px;
border-radius: 2px;
cursor: pointer;
transition: none;
}
.filter-tag-btn:hover {
border-color: var(--accent-cyan);
color: var(--text-primary);
background-color: var(--bg-elevated);
}
.filter-tag-btn.active {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
border-color: var(--accent-cyan);
font-weight: 700;
}
/* Asymmetric Split Grid */
.split-grid {
display: grid;
grid-template-columns: 1.25fr 0.75fr;
gap: 16px;
}
@media (max-width: 880px) {
.split-grid {
grid-template-columns: 1fr;
}
}
/* Standard Tile Container */
.tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 20px;
display: flex;
flex-direction: column;
gap: 14px;
}
.tile-header {
display: flex;
justify-content: space-between;
align-items: baseline;
border-bottom: 1px solid var(--border-color);
padding-bottom: 10px;
}
.tile-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.92rem;
font-weight: 700;
color: var(--text-primary);
display: flex;
align-items: center;
gap: 8px;
}
.tile-meta {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.74rem;
color: var(--text-muted);
}
/* Featured Lead Article Card (Inside Tile) */
.featured-card-body {
display: flex;
flex-direction: column;
gap: 12px;
}
.featured-badge-row {
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.76rem;
flex-wrap: wrap;
gap: 8px;
}
.badge-pinned {
color: var(--accent-amber);
font-weight: 700;
}
.featured-article-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 1.35rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
line-height: 1.3;
transition: none;
}
.featured-article-title:hover {
color: var(--accent-cyan);
}
.featured-prose {
font-size: 0.92rem;
color: var(--text-primary);
line-height: 1.6;
}
/* Terminal Code Block Component */
.terminal-code-box {
border: 1px solid var(--border-color);
border-radius: 3px;
background-color: var(--bg-canvas);
overflow: hidden;
font-family: 'JetBrains Mono', monospace;
}
.code-titlebar {
background-color: var(--bg-surface);
border-bottom: 1px solid var(--border-color);
padding: 6px 12px;
font-size: 0.74rem;
color: var(--text-muted);
display: flex;
justify-content: space-between;
}
.code-content {
padding: 12px;
font-size: 0.78rem;
overflow-x: auto;
color: var(--text-primary);
line-height: 1.5;
}
.featured-cta-row {
display: flex;
justify-content: space-between;
align-items: center;
padding-top: 10px;
border-top: 1px solid var(--border-color);
flex-wrap: wrap;
gap: 10px;
font-family: 'IBM Plex Mono', monospace;
}
.cta-button {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
padding: 6px 14px;
font-weight: 700;
font-size: 0.8rem;
text-decoration: none;
border-radius: 2px;
border: 1px solid var(--accent-cyan);
transition: none;
}
.cta-button:hover {
background-color: transparent;
color: var(--accent-cyan);
}
/* Sidebar Tile Elements */
.sidebar-stats-box {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 12px 14px;
display: flex;
flex-direction: column;
gap: 8px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
color: var(--text-muted);
}
.stat-row {
display: flex;
justify-content: space-between;
}
.stat-val {
color: var(--text-primary);
font-weight: 700;
}
.topic-track-item {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 10px 12px;
display: flex;
flex-direction: column;
gap: 4px;
text-decoration: none;
transition: none;
}
.topic-track-item:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.topic-track-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.84rem;
font-weight: 700;
color: var(--text-primary);
}
.topic-track-item:hover .topic-track-title {
color: var(--accent-cyan);
}
.topic-track-desc {
font-size: 0.78rem;
color: var(--text-muted);
line-height: 1.4;
}
/* Full-Width Chronological Article Feed Tile */
.feed-list {
display: flex;
flex-direction: column;
gap: 12px;
}
.feed-card {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 16px 18px;
display: flex;
flex-direction: column;
gap: 8px;
transition: none;
}
.feed-card:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.feed-meta-row {
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.76rem;
color: var(--text-muted);
}
.feed-date {
color: var(--accent-cyan);
}
.feed-heading {
font-family: 'IBM Plex Mono', monospace;
font-size: 1.1rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
line-height: 1.35;
transition: none;
}
.feed-card:hover .feed-heading {
color: var(--accent-cyan);
}
.feed-excerpt {
font-size: 0.9rem;
color: var(--text-primary);
line-height: 1.6;
}
.feed-tags-row {
display: flex;
justify-content: space-between;
align-items: center;
padding-top: 6px;
border-top: 1px solid var(--border-color);
font-family: 'IBM Plex Mono', monospace;
font-size: 0.74rem;
color: var(--text-muted);
flex-wrap: wrap;
gap: 6px;
}
.tag-cluster {
display: flex;
gap: 8px;
}
/* Global Footer Tile (Gateway 3 Standard) */
.footer-tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 12px 20px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
color: var(--text-muted);
flex-wrap: wrap;
gap: 10px;
}
.footer-links-cluster {
display: flex;
gap: 12px;
align-items: center;
}
.footer-btn {
color: var(--text-primary);
text-decoration: none;
padding: 2px 4px;
transition: none;
}
.footer-btn:hover {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
}
.pipe {
color: var(--border-color);
}
</style>
</head>
<body>
<main class="tiling-layout">
<!-- Top Global Status Bar (Gateway 3 Match) -->
<header class="global-bar">
<div class="brand-group">
<span class="status-indicator"></span>
<span>RIVER ROOKS // BLOG &amp; RESEARCH ARCHIVE</span>
</div>
<nav class="bar-nav" aria-label="Quick Navigation">
<a href="service-gateway-tiling.html" class="bar-link">Gateway 3 ↗</a>
<a href="#" class="bar-link active">&gt; Dispatches</a>
<a href="https://git.rooks.dev" target="_blank" rel="noopener" class="bar-link">Git Forge</a>
<a href="feed.xml" class="bar-link">RSS Feed</a>
<a href="index.html" class="bar-link">Catalog ↗</a>
</nav>
</header>
<!-- Hero Tile: Blog Mission & Topic Filters -->
<section class="hero-tile" aria-label="Blog Mission & Overview">
<div class="hero-pretitle">TECHNICAL PUBLICATION REPOSITORY &bull; ~/NOTES/INDEX.MD</div>
<h1 class="hero-main-title">Engineering Notes, CTF Write-Ups &amp; Systems Architecture</h1>
<p class="hero-landing-text">
Documenting bare-metal systems, embedded hardware audits, and network isolation architectures. Writing zero-allocation POSIX scripts, reverse engineering production microcontrollers, and analyzing memory allocator exploitation primitives.
</p>
<div class="filter-pills-row">
<span style="color: var(--text-muted); margin-right: 4px;">TOPIC FILTER:</span>
<button class="filter-tag-btn active" onclick="filterTopic('all', this)">[All Dispatches (5)]</button>
<button class="filter-tag-btn" onclick="filterTopic('firmware', this)">[#firmware (1)]</button>
<button class="filter-tag-btn" onclick="filterTopic('homelab', this)">[#homelab (2)]</button>
<button class="filter-tag-btn" onclick="filterTopic('security', this)">[#security (3)]</button>
<button class="filter-tag-btn" onclick="filterTopic('posix-sh', this)">[#posix-sh (1)]</button>
</div>
</section>
<!-- Split Grid: Featured Article + Research Index -->
<div class="split-grid">
<!-- Left Column: Featured Article Tile -->
<section class="tile" aria-label="Featured Technical Article">
<div class="tile-header">
<div class="tile-title">
<span>// PINNED RESEARCH WRITE-UP</span>
</div>
<span class="tile-meta">SPI FLASH &bull; 8 MIN READ</span>
</div>
<div class="featured-card-body">
<div class="featured-badge-row">
<span class="badge-pinned">[FEATURED DEEP DIVE]</span>
<span style="color: var(--text-muted);">2026-07-20 &bull; ~/notes/iot-firmware-spi-extraction.md</span>
</div>
<h2 style="margin: 0;">
<a href="article-tiling-firmware.html" class="featured-article-title">Reverse Engineering IoT Firmware: SPI Flash Extraction</a>
</h2>
<p class="featured-prose">
In security audits of embedded systems, retrieving firmware is the critical first step. When over-the-air updates are encrypted and debug ports (UART, JTAG) are disabled in production silicon, dumping physical SPI Flash memory becomes necessary. This writeup covers extracting firmware from an 8-pin SOP SPI flash chip using a Bus Pirate and flashrom to bypass bootloader lockdowns.
</p>
<!-- Terminal Code Box -->
<div class="terminal-code-box">
<div class="code-titlebar">
<span>extract_firmware.sh</span>
<span>POSIX sh</span>
</div>
<div class="code-content">
<pre><code># Query the SPI flash details using flashrom via Bus Pirate
flashrom -p buspirate_spi:dev=/dev/ttyUSB0,spispeed=1M -r firmware_dump.bin
# Verify the integrity of the binary dump by comparing hashes
if [ $? -eq 0 ]; then
echo "Dump successful. Running md5sum..."
md5sum firmware_dump.bin
fi</code></pre>
</div>
</div>
<div class="featured-cta-row">
<div class="tag-cluster">
<span style="color: var(--text-muted); font-size: 0.75rem;">[#firmware] [#hardware] [#security] [#bus-pirate]</span>
</div>
<a href="article-tiling-firmware.html" class="cta-button">READ FULL WRITEUP &rarr;</a>
</div>
</div>
</section>
<!-- Right Column: Quick Research Tracks & Telemetry -->
<div style="display: flex; flex-direction: column; gap: 16px;">
<!-- Publication Stats Tile -->
<section class="tile" aria-label="Archive Statistics">
<div class="tile-header">
<div class="tile-title">
<span>// ARCHIVE TELEMETRY</span>
</div>
<span class="tile-meta">STATIC HTML</span>
</div>
<div class="sidebar-stats-box">
<div class="stat-row">
<span>TOTAL ARTICLES:</span>
<span class="stat-val">5 PUBLISHED</span>
</div>
<div class="stat-row">
<span>TOTAL READING TIME:</span>
<span class="stat-val">51 MINUTES</span>
</div>
<div class="stat-row">
<span>ACTIVE TOPICS:</span>
<span class="stat-val">7 CATEGORIES</span>
</div>
<div class="stat-row">
<span>FORMAT COMPLIANCE:</span>
<span class="stat-val">IEEE STD 1003.1</span>
</div>
</div>
</section>
<!-- Curated Focus Tracks -->
<section class="tile" aria-label="Curated Topic Tracks">
<div class="tile-header">
<div class="tile-title">
<span>// RESEARCH TRACKS</span>
</div>
<span class="tile-meta">CURATED</span>
</div>
<div style="display: flex; flex-direction: column; gap: 8px;">
<a href="#" class="topic-track-item">
<div class="topic-track-title">&gt; Embedded &amp; Hardware Forensics</div>
<div class="topic-track-desc">Flash memory dumping, bus tapping, silicon pinout discovery.</div>
</a>
<a href="#" class="topic-track-item">
<div class="topic-track-title">&gt; Network Routing &amp; Homelab</div>
<div class="topic-track-desc">Traefik reverse proxying, WireGuard full-mesh, VLAN firewalls.</div>
</a>
<a href="#" class="topic-track-item">
<div class="topic-track-title">&gt; Low-Level Memory Exploitation</div>
<div class="topic-track-desc">glibc tcache safe-linking, heap corruption, House of Apple.</div>
</a>
</div>
</section>
</div>
</div>
<!-- Full-Width Article Feed Tile -->
<section class="tile" aria-label="Chronological Article Stream">
<div class="tile-header">
<div class="tile-title">
<span>// CHRONOLOGICAL DISPATCHES FEED</span>
</div>
<span class="tile-meta">ALL ARTICLES ORDERED BY DATE</span>
</div>
<div class="feed-list" id="feedList">
<!-- Post 2: Traefik -->
<article class="feed-card" data-tags="homelab networking">
<div class="feed-meta-row">
<time datetime="2026-07-15" class="feed-date">2026-07-15 &bull; 12 min read</time>
<span>~/notes/ha-traefik-docker.md</span>
</div>
<h3 style="margin: 0;">
<a href="article-tiling-traefik.html" class="feed-heading">&gt; Building a High-Availability Traefik Router with Docker Compose</a>
</h3>
<p class="feed-excerpt">
Architecting automated TLS wildcard certificate propagation, Docker provider label routing, zero-downtime container updates, and backend health-check failover routes on bare-metal infrastructure.
</p>
<div class="feed-tags-row">
<div class="tag-cluster">
<span>[#homelab]</span>
<span>[#docker-traefik]</span>
<span>[#networking]</span>
</div>
<a href="article-tiling-traefik.html" style="color: var(--accent-cyan); text-decoration: none;">Read Entry &rarr;</a>
</div>
</article>
<!-- Post 3: POSIX sh -->
<article class="feed-card" data-tags="posix-sh security">
<div class="feed-meta-row">
<time datetime="2026-07-10" class="feed-date">2026-07-10 &bull; 6 min read</time>
<span>~/notes/posix-sh-vs-bash.md</span>
</div>
<h3 style="margin: 0;">
<a href="#" class="feed-heading">&gt; POSIX sh vs. Bash: Portability in Modern Scripts</a>
</h3>
<p class="feed-excerpt">
Analyzing edge-case incompatibilities, syntax overhead, eliminating bashisms, and writing fast, bulletproof bootstrapping scripts for Alpine and embedded targets conforming to IEEE Std 1003.1.
</p>
<div class="feed-tags-row">
<div class="tag-cluster">
<span>[#posix-sh]</span>
<span>[#shell]</span>
<span>[#unix]</span>
</div>
<a href="#" style="color: var(--accent-cyan); text-decoration: none;">Read Entry &rarr;</a>
</div>
</article>
<!-- Post 4: Heap Exploitation -->
<article class="feed-card" data-tags="security">
<div class="feed-meta-row">
<time datetime="2026-06-28" class="feed-date">2026-06-28 &bull; 15 min read</time>
<span>~/notes/ctf-heap-glibc-2-35.md</span>
</div>
<h3 style="margin: 0;">
<a href="article-tiling-heap.html" class="feed-heading">&gt; CTF Write-up: Heap Exploitation in glibc 2.35</a>
</h3>
<p class="feed-excerpt">
Deconstructing modern glibc memory allocator defenses: tcache safe-linking pointer mangling, bypass primitives, and House of Apple file structure hijacking for arbitrary code execution.
</p>
<div class="feed-tags-row">
<div class="tag-cluster">
<span>[#ctf]</span>
<span>[#binary-exploitation]</span>
<span>[#security]</span>
</div>
<a href="article-tiling-heap.html" style="color: var(--accent-cyan); text-decoration: none;">Read Entry &rarr;</a>
</div>
</article>
<!-- Post 5: Zero-Trust WireGuard -->
<article class="feed-card" data-tags="networking security homelab">
<div class="feed-meta-row">
<time datetime="2026-06-14" class="feed-date">2026-06-14 &bull; 10 min read</time>
<span>~/notes/zero-trust-wireguard-opnsense.md</span>
</div>
<h3 style="margin: 0;">
<a href="#" class="feed-heading">&gt; Zero-Trust Network Isolation with WireGuard &amp; OPNsense VLANs</a>
</h3>
<p class="feed-excerpt">
Designing strict zone-based firewall rules across isolated VLANs (Management, Server DMZ, IoT, Trusted Clients) with point-to-point WireGuard cryptographic routing.
</p>
<div class="feed-tags-row">
<div class="tag-cluster">
<span>[#networking]</span>
<span>[#wireguard]</span>
<span>[#security]</span>
</div>
<a href="#" style="color: var(--accent-cyan); text-decoration: none;">Read Entry &rarr;</a>
</div>
</article>
</div>
</section>
<!-- Global Footer Tile (Matching Gateway 3 Exactly) -->
<footer class="footer-tile">
<div>River Rooks &bull; University of Alabama College of Engineering</div>
<nav class="footer-links-cluster" aria-label="Global Footer Links">
<a href="service-gateway-tiling.html" class="footer-btn">Gateway Lander</a>
<span class="pipe">|</span>
<a href="feed.xml" class="footer-btn">RSS</a>
<span class="pipe">|</span>
<a href="https://git.rooks.dev" target="_blank" rel="noopener" class="footer-btn">Forgejo</a>
<span class="pipe">|</span>
<a href="mailto:river@rooks.dev" class="footer-btn">river@rooks.dev</a>
<span class="pipe">|</span>
<a href="#" title="Fingerprint: 0x4A8E92F1C0B3D4E7" class="footer-btn">PGP</a>
<span class="pipe">|</span>
<a href="index.html" class="footer-btn">Catalog ↗</a>
</nav>
</footer>
</main>
<script>
function filterTopic(topic, btn) {
document.querySelectorAll('.filter-tag-btn').forEach(el => el.classList.remove('active'));
btn.classList.add('active');
const cards = document.querySelectorAll('#feedList .feed-card');
cards.forEach(card => {
if (topic === 'all') {
card.style.display = 'flex';
} else {
const tags = card.getAttribute('data-tags') || '';
if (tags.includes(topic)) {
card.style.display = 'flex';
} else {
card.style.display = 'none';
}
}
});
}
</script>
</body>
</html>
sample-designs/design-specification.md
-81
View File
@@ -1,81 +0,0 @@
# Project Brief: Technical Web Architecture & Blog
**Project Type:** Personal Blog & Technical Documentation Site
**Design Philosophy:** High-signal, low-noise. Developer-centric minimalism.
**Vibe/Comparisons:** Zed Editor, Ghostty, Noctalia.dev.
**Strictly Avoid:** Raycast, Astro, Vercel-style "SaaS" aesthetics.
## 1. Executive Summary
This project requires a web interface that feels like a native development environment or terminal emulator, not a marketing page. The design must prioritize raw performance, keyboard navigability, and information density. It should evoke the craftsmanship of tiling window managers and modal text editors.
The content will heavily feature deep technical writing, including CTF write-ups, network routing diagrams, Docker/Traefik architectures, and raw code snippets (Lua, POSIX `sh`, and Python). The design must accommodate high-density information without visual clutter.
---
## 2. Global Rules & Anti-Patterns
To achieve the correct aesthetic, the designer must adhere to strict constraints.
> **The "Do Not Use" List**
> * **NO Glassmorphism:** Zero use of `backdrop-filter: blur()`, frosted glass, or translucent overlays.
> * **NO Glows or Drop Shadows:** Elements should not float, glow, or cast shadows. Depth is created through crisp 1px borders and distinct surface colors.
> * **NO Gradients:** Avoid sweeping linear or radial gradients. Stick to solid colors.
> * **NO Spring Animations:** Avoid floaty, delayed transitions.
> * **NO Rounded Blobs:** Keep border-radii minimal (0px to 4px max). Sharp corners are preferred.
---
## 3. Typography System
The typographical hierarchy is a hybrid system utilizing monospace fonts for structural elements and a clean sans-serif for long-form reading.
| Usage | Font Family Preference | Weight | Role |
| :--- | :--- | :--- | :--- |
| **Structural / UI** | IBM Plex Mono, JetBrains Mono | Regular (400), Medium (500) | Navigation links, metadata, dates, tags, timestamps, buttons. |
| **Code Blocks** | JetBrains Mono, Fira Code | Regular (400) | Inline code snippets, terminal command blocks, scripts. |
| **Body Prose** | Inter, Geist Sans, Roboto | Regular (400) | Standard article paragraphs, lists. |
| **Headings (H1-H3)**| IBM Plex Mono (or Sans variant) | Bold (700) | Article titles, section headers. |
**Typographical Constraints:**
* **Line Height:** `1.6` to `1.7` for prose.
* **Max Width:** Cap article text at `65ch` (characters) for optimal readability.
---
## 4. Color Palette (Dark Mode Native)
The site does not need a light mode. It should be built as a dark-mode native experience using a muted, low-saturation charcoal palette, mimicking a modern terminal or IDE.
* **Base Canvas (`#121417` or `#0d0f12`):** A deep slate/charcoal. Not pure black (`#000000`), which causes eye strain.
* **Surface / Card (`#1c1f26`):** Slightly lighter than the canvas for article blocks or terminal windows.
* **Borders & Dividers (`#2b303b`):** Subtle, low-contrast 1px solid lines used to define grids and separate content.
* **Primary Text (`#e0e6f0`):** Off-white/light ash for prose.
* **Muted Text (`#8a95a5`):** For timestamps, metadata, and non-essential UI text.
* **Accent Color (Designer's Choice):** One single, vibrant terminal color (e.g., ANSI Green, Amber, or Cyan) used sparingly for active states, link hovers, or terminal prompts (like `>`).
---
## 5. Layout & Component Architecture
The layout should be heavily grid-based, feeling structural and deliberate.
### Core Components Needed
1. **Terminal-Style Code Blocks:** Must support syntax highlighting. Should include a simple header (e.g., showing the filename like `config.lua` or `docker-compose.yml`) with a 1px border.
2. **Metadata Tags:** Small, monospaced inline blocks for categorizing posts (e.g., `[#homelab]`, `[#ctf]`, `[#hyprland]`).
3. **Keyboard Shortcut Hints:** Visual styling for `<kbd>` elements, rendering as crisp, bordered boxes (e.g., `Ctrl` + `K`).
4. **Index/Archive List:** A dense, tabular list for older posts, prioritized by date, title, and tags, rather than large image thumbnails.
### Spacing & Grid
* Use a rigid 4pt or 8pt baseline grid.
* Padding inside code blocks and cards should be dense but mathematically consistent.
* Full-bleed horizontal dividers (`<hr>`) should be used to separate major sections instead of large margins.
---
## 6. Interaction & Motion
Interactivity should mirror command-line interfaces: fast, binary, and unembellished.
* **Hover States:** Immediate state changes. Instead of fading a button's background over `300ms`, snap the background color instantly or invert the text/background colors.
* **Focus States:** Explicit, high-visibility 1px or 2px solid outlines (using the accent color) when navigating via the `Tab` key. Accessibility and keyboard navigation are paramount.
* **Active Elements:** Use structural indicators (like a `>` prepended to an active navigation link, or a solid left-border block) rather than changing font sizes or scaling elements up.
sample-designs/service-gateway-tiling.html
-592
View File
@@ -1,592 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>River Rooks | Homelab Gateway (Tiling Workspace)</title>
<style>
@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,700;1,400&family=Inter:wght@400;500;700&family=JetBrains+Mono:ital,wght@0,400;0,500;1,400&display=swap');
:root {
--bg-canvas: #0d0f12; /* Deep slate/charcoal canvas */
--bg-surface: #121417; /* Tile surface */
--bg-elevated: #1c1f26; /* Hovered tile */
--border-color: #2b303b; /* Crisp 1px border */
--text-primary: #e0e6f0; /* Prose off-white */
--text-muted: #8a95a5; /* Monospace metadata */
--accent-cyan: #00f0ff; /* Primary active accent */
--accent-green: #00e676; /* Online indicator */
--accent-amber: #ffb700; /* Warning / internal indicator */
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
background-color: var(--bg-canvas);
color: var(--text-primary);
font-family: 'Inter', sans-serif;
line-height: 1.6;
min-height: 100vh;
display: flex;
flex-direction: column;
align-items: center;
padding: 24px 16px 48px 16px;
}
.tiling-layout {
width: 100%;
max-width: 1120px;
display: flex;
flex-direction: column;
gap: 16px;
}
/* Top Global Status Header Bar */
.global-bar {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 10px 18px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.8rem;
flex-wrap: wrap;
gap: 10px;
}
.brand-group {
display: flex;
align-items: center;
gap: 10px;
color: var(--text-primary);
font-weight: 700;
}
.status-indicator {
width: 8px;
height: 8px;
background-color: var(--accent-green);
display: inline-block;
}
.bar-nav {
display: flex;
gap: 14px;
align-items: center;
}
.bar-link {
color: var(--text-muted);
text-decoration: none;
transition: none; /* Instant snap */
}
.bar-link:hover {
color: var(--accent-cyan);
}
/* Primary Hero Landing Tile (Main Focus of Homepage) */
.hero-tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-left: 3px solid var(--accent-cyan);
border-radius: 4px;
padding: 28px 32px;
display: flex;
flex-direction: column;
gap: 16px;
}
.hero-pretitle {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.8rem;
color: var(--accent-cyan);
letter-spacing: 0.06em;
text-transform: uppercase;
}
.hero-main-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 2.2rem;
font-weight: 700;
color: var(--text-primary);
letter-spacing: -0.02em;
line-height: 1.2;
}
.hero-landing-text {
font-size: 1.02rem;
color: var(--text-primary);
line-height: 1.7;
max-width: 80ch;
}
.hero-landing-text p {
margin-bottom: 14px;
}
.hero-landing-text p:last-child {
margin-bottom: 0;
}
.hero-directive-box {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 14px 18px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.84rem;
color: var(--text-muted);
line-height: 1.6;
}
.hero-directive-box strong {
color: var(--text-primary);
}
/* Tiling Grid Section: Split Columns */
.split-grid {
display: grid;
grid-template-columns: 1.15fr 0.85fr;
gap: 16px;
}
@media (max-width: 880px) {
.split-grid {
grid-template-columns: 1fr;
}
}
/* Tile Container Style */
.tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 20px;
display: flex;
flex-direction: column;
gap: 14px;
}
.tile-header {
display: flex;
justify-content: space-between;
align-items: baseline;
border-bottom: 1px solid var(--border-color);
padding-bottom: 10px;
}
.tile-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.95rem;
font-weight: 700;
color: var(--text-primary);
display: flex;
align-items: center;
gap: 8px;
}
.tile-meta {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.74rem;
color: var(--text-muted);
}
/* Featured Service Tile: The Blog */
.blog-service-feature {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 16px;
display: flex;
flex-direction: column;
gap: 10px;
}
.blog-feature-top {
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
}
.badge-core {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
padding: 2px 6px;
font-weight: 700;
border-radius: 2px;
}
.blog-feature-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 1.15rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
display: inline-block;
transition: none;
}
.blog-feature-title:hover {
color: var(--accent-cyan);
}
.blog-feature-desc {
font-size: 0.9rem;
color: var(--text-primary);
line-height: 1.5;
}
.blog-sublinks {
display: flex;
flex-direction: column;
gap: 6px;
margin-top: 4px;
border-top: 1px solid var(--border-color);
padding-top: 10px;
}
.blog-sublink-item {
display: flex;
justify-content: space-between;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.8rem;
color: var(--text-primary);
text-decoration: none;
padding: 4px 6px;
border-radius: 2px;
transition: none;
}
.blog-sublink-item:hover {
background-color: var(--bg-elevated);
color: var(--accent-cyan);
}
/* Homelab Services Grid */
.services-mini-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 10px;
}
@media (max-width: 540px) {
.services-mini-grid {
grid-template-columns: 1fr;
}
}
.service-tile-item {
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
padding: 12px;
text-decoration: none;
display: flex;
flex-direction: column;
justify-content: space-between;
gap: 6px;
transition: none;
}
.service-tile-item:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.service-item-title {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.88rem;
font-weight: 700;
color: var(--text-primary);
}
.service-tile-item:hover .service-item-title {
color: var(--accent-cyan);
}
.service-item-tag {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.7rem;
color: var(--text-muted);
}
.service-item-desc {
font-size: 0.8rem;
color: var(--text-muted);
line-height: 1.4;
}
/* Infrastructure Nodes Telemetry Tile */
.node-stat-row {
display: flex;
justify-content: space-between;
align-items: center;
padding: 8px 10px;
background-color: var(--bg-canvas);
border: 1px solid var(--border-color);
border-radius: 3px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
}
.node-name {
color: var(--text-primary);
font-weight: 700;
}
.node-load {
color: var(--accent-green);
}
/* Bottom Global Footer Tile */
.footer-tile {
background-color: var(--bg-surface);
border: 1px solid var(--border-color);
border-radius: 4px;
padding: 12px 20px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
color: var(--text-muted);
flex-wrap: wrap;
gap: 10px;
}
.footer-links-cluster {
display: flex;
gap: 12px;
align-items: center;
}
.footer-btn {
color: var(--text-primary);
text-decoration: none;
padding: 2px 4px;
transition: none;
}
.footer-btn:hover {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
}
.pipe {
color: var(--border-color);
}
</style>
</head>
<body>
<main class="tiling-layout">
<!-- Top Status Bar -->
<header class="global-bar">
<div class="brand-group">
<span class="status-indicator"></span>
<span>RIVER ROOKS // NODE GATEWAY</span>
</div>
<nav class="bar-nav" aria-label="Quick Nav">
<a href="blog-lander-cards.html" class="bar-link">&gt; Blog &amp; Notes</a>
<a href="homelab.html" class="bar-link">Infrastructure</a>
<a href="https://git.rooks.dev" target="_blank" rel="noopener" class="bar-link">Git Forge</a>
<a href="index.html" class="bar-link">Catalog ↗</a>
</nav>
</header>
<!-- Main Hero Landing Tile (Central Focus of Homepage) -->
<section class="hero-tile" aria-label="Homepage Mission & Landing Declaration">
<div class="hero-pretitle">SYSTEM DECLARATION &bull; RACK-01 NODE GATEWAY</div>
<h1 class="hero-main-title">Cybersecurity &amp; Dev Ops notes</h1>
<div class="hero-landing-text">
<p>
I am River Rooks, a cybersecurity student at the University of Alabama. My work centers on self-hosted system architecture, network security, and capture the flag style skills. I maintain a personal homelab cluster for research, experimentation, and development of open-source tools.
</p>
<p>
This website functions as the unified frontend for my physical homelab cluster. Rather than hosting projects on opaque third-party clouds, everything here runs on bare metal in my personal server rack—orchestrated through Proxmox VE, partitioned across isolated VLANs via OPNsense, and protected by point-to-point WireGuard cryptographic meshes.
</p>
<p>
<strong>Navigation Guide:</strong> If you are here to read technical research, the <strong>Engineering Blog</strong> is linked below with deep write-ups on firmware dumping, heap exploitation, and container routing. If you are here to use tools, the <strong>Public Services</strong> provide locally hosted instances of CyberChef, Stirling PDF, and Git.
</p>
</div>
<div class="hero-directive-box">
<strong>PRIMARY DESTINATIONS:</strong>
<span style="color: var(--accent-cyan); margin-left: 8px;">[1] Technical Blog (5 Articles)</span> &bull;
<span>[2] Forgejo Git Repos</span> &bull;
<!-- <span>[3] Public Cryptographic &amp; PDF Tools</span> &bull; -->
<!-- <span>[4] Cluster Telemetry</span> -->
</div>
</section>
<!-- Split Tiling Columns -->
<div class="split-grid">
<!-- Left Column: Featured Service (Blog) + Recent Articles -->
<div style="display: flex; flex-direction: column; gap: 16px;">
<!-- Featured Service Tile: The Blog -->
<section class="tile" aria-label="Featured Service: Technical Blog">
<div class="tile-header">
<div class="tile-title">
<span>// PRIMARY SERVICE: THE TECHNICAL BLOG</span>
</div>
<span class="tile-meta">~/notes/ &bull; 5 ARTICLES</span>
</div>
<div class="blog-service-feature">
<div class="blog-feature-top">
<span class="badge-core">[CORE PUBLICATION SERVICE]</span>
<span style="color: var(--text-muted);">2026-07-20 LAST SYNC</span>
</div>
<a href="blog-lander-cards.html" class="blog-feature-title">&gt; River Rooks Technical Notes &amp; Research</a>
<p class="blog-feature-desc">
In-depth security post-mortems, CTF write-ups, shell portability benchmarks, and bare-metal homelab architecture guides.
</p>
<div class="blog-sublinks">
<a href="blog-lander-cards.html" class="blog-sublink-item">
<span>1. Reverse Engineering IoT Firmware (SPI Flash)</span>
<span style="color: var(--accent-cyan);">[8 min] &rarr;</span>
</a>
<a href="blog-lander-cards.html" class="blog-sublink-item">
<span>2. High-Availability Traefik with Docker Compose</span>
<span style="color: var(--accent-cyan);">[12 min] &rarr;</span>
</a>
<a href="blog-lander-cards.html" class="blog-sublink-item">
<span>3. POSIX sh vs. Bash: Portability in Modern Scripts</span>
<span style="color: var(--accent-cyan);">[6 min] &rarr;</span>
</a>
<a href="blog-lander-cards.html" class="blog-sublink-item">
<span>4. CTF Write-up: Heap Exploitation in glibc 2.35</span>
<span style="color: var(--accent-cyan);">[15 min] &rarr;</span>
</a>
</div>
</div>
</section>
</div>
<!-- Right Column: Homelab Hosted Services & Node Telemetry -->
<div style="display: flex; flex-direction: column; gap: 16px;">
<!-- Hosted Services Tile -->
<section class="tile" aria-label="Homelab Services Directory">
<div class="tile-header">
<div class="tile-title">
<span>// HOMELAB SERVICES ROUTER</span>
</div>
<span class="tile-meta">4 PUBLIC TOOLS</span>
</div>
<div class="services-mini-grid">
<a href="https://git.rooks.dev" target="_blank" rel="noopener" class="service-tile-item">
<div>
<div class="service-item-title">Forgejo Git</div>
<div class="service-item-tag">git.rooks.dev:2222</div>
</div>
<p class="service-item-desc">Self-hosted code repositories &amp; dotfiles.</p>
</a>
<a href="https://chef.rooks.dev" target="_blank" rel="noopener" class="service-tile-item">
<div>
<div class="service-item-title">CyberChef</div>
<div class="service-item-tag">chef.rooks.dev:443</div>
</div>
<p class="service-item-desc">Hex decoding, cryptography &amp; forensics.</p>
</a>
<a href="https://pdf.rooks.dev" target="_blank" rel="noopener" class="service-tile-item">
<div>
<div class="service-item-title">Stirling PDF</div>
<div class="service-item-tag">pdf.rooks.dev:443</div>
</div>
<p class="service-item-desc">Private document OCR and manipulation.</p>
</a>
<a href="https://status.rooks.dev" target="_blank" rel="noopener" class="service-tile-item">
<div>
<div class="service-item-title">Uptime Kuma</div>
<div class="service-item-tag">status.rooks.dev:3001</div>
</div>
<p class="service-item-desc">Live synthetic latency &amp; uptime telemetry.</p>
</a>
</div>
</section>
<!-- Bare-Metal Node Telemetry Tile -->
<section class="tile" aria-label="Physical Hardware Nodes">
<div class="tile-header">
<div class="tile-title">
<span>// HARDWARE NODES (RACK-01)</span>
</div>
<span class="tile-meta">10GbE SFP+</span>
</div>
<div style="display: flex; flex-direction: column; gap: 8px;">
<div class="node-stat-row">
<div>
<span class="node-name">gw-node01.lan</span>
<span style="color: var(--text-muted); font-size: 0.72rem; margin-left: 6px;">OPNsense 24.7</span>
</div>
<span class="node-load">CPU: 18% | RAM: 32%</span>
</div>
<div class="node-stat-row">
<div>
<span class="node-name">pve-node02.lan</span>
<span style="color: var(--text-muted); font-size: 0.72rem; margin-left: 6px;">Proxmox VE (AMD 5900X)</span>
</div>
<span class="node-load">CPU: 42% | RAM: 68%</span>
</div>
<div class="node-stat-row">
<div>
<span class="node-name">nas-node03.lan</span>
<span style="color: var(--text-muted); font-size: 0.72rem; margin-left: 6px;">TrueNAS (48TB RaidZ2)</span>
</div>
<span class="node-load">CPU: 14% | RAM: 82%</span>
</div>
</div>
</section>
</div>
</div>
<!-- Global Footer Bar -->
<footer class="footer-tile">
<div>River Rooks &bull; University of Alabama College of Engineering</div>
<nav class="footer-links-cluster" aria-label="Global Footer Links">
<a href="blog-lander-cards.html" class="footer-btn">Blog Lander</a>
<span class="pipe">|</span>
<a href="feed.xml" class="footer-btn">RSS</a>
<span class="pipe">|</span>
<a href="https://git.rooks.dev" target="_blank" rel="noopener" class="footer-btn">Forgejo</a>
<span class="pipe">|</span>
<a href="mailto:river@rooks.dev" class="footer-btn">river@rooks.dev</a>
<span class="pipe">|</span>
<a href="#" title="Fingerprint: 0x4A8E92F1C0B3D4E7" class="footer-btn">PGP</a>
<span class="pipe">|</span>
<a href="index.html" class="footer-btn">Catalog ↗</a>
</nav>
</footer>
</main>
</body>
</html>
sample-docker-compose.yml
+17 -25
View File
@@ -1,38 +1,30 @@
services:
web:
# Pull prebuilt engine image from your Gitea registry
x-blog-templage: &blog-base
image: git.riverrooks.dev/venus/river-rooks-blog:latest
# Local build fallback (optional when building image locally)
# build:
# context: .
# dockerfile: Dockerfile
# args:
# SITE_DOMAIN: "${SITE_DOMAIN:?Error: SITE_DOMAIN is not set. Please define SITE_DOMAIN in .env}"
# SITE_URL: "${SITE_URL:-https://${SITE_DOMAIN}}"
# PORT: "${PORT:-8080}"
container_name: river_rooks_web
restart: unless-stopped
# Healthcheck is natively baked into the Dockerfile image metadata
volumes:
- "./posts:/app/src/posts"
environment:
- "SITE_DOMAIN=${SITE_DOMAIN:?Error: SITE_DOMAIN is not set. Please define SITE_DOMAIN in .env}"
- "SITE_URL=${SITE_URL:-https://${SITE_DOMAIN}}"
- "PORT=${PORT:-8080}"
- "WATCH=${WATCH:-false}"
volumes:
# Mount external markdown posts directly into the container
- "./posts:/app/src/posts"
- "WATCH=true"
- "API_SECRET=${API_SECRET}"
ports:
- "${HOST_PORT:-${PORT:-8080}}:${PORT:-8080}"
networks:
- backend
labels:
- "traefik.enable=true"
- "traefik.http.routers.blog.rule=Host(`riverrooks.dev`) || Host(`www.riverrooks.dev`)"
- "traefik.http.routers.blog.entrypoints=websecure"
- "traefik.http.routers.blog.tls.certresolver=basic"
- "traefik.http.services.blog.loadbalancer.server.port=8080"
- "traefik.docker.network=backend"
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:${PORT:-8080}/healthz > /dev/null || exit 1"]
interval: 5s
timeout: 3s
retries: 3
start_period: 5s
# I Have this deployed with a series of traefik labels but that's not strictly nessescary
services:
blog-blue:
<<: *blog-base
blog-green:
<<: *blog-base
networks:
backend:
external: true
server.js
-413
View File
@@ -1,413 +0,0 @@
import http from "node:http";
import fs from "node:fs";
import path from "node:path";
import { exec } from "node:child_process";
import { fileURLToPath } from "node:url";
const MIME_TYPES = {
".html": "text/html; charset=utf-8",
".css": "text/css; charset=utf-8",
".js": "application/javascript; charset=utf-8",
".mjs": "application/javascript; charset=utf-8",
".json": "application/json; charset=utf-8",
".xml": "application/xml; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".webp": "image/webp",
".gif": "image/gif",
".ico": "image/x-icon",
".woff": "font/woff",
".woff2": "font/woff2",
".ttf": "font/ttf",
".txt": "text/plain; charset=utf-8"
};
/**
* Normalizes Obsidian-specific syntax (wikilinks, internal attachments)
* into standard web URLs and image references.
* @param {string} content Raw Markdown content from Obsidian
* @returns {string} Normalized Markdown content
*/
export function normalizeObsidianMarkdown(content) {
if (typeof content !== "string") return "";
let normalized = content;
// Bridge created -> date so Eleventy collections sorting and filters work seamlessly
const createdMatch = normalized.match(/^created:\s*([^\r\n]+)$/m);
const hasDate = /^date:\s*.+$/m.test(normalized);
if (createdMatch && !hasDate) {
normalized = normalized.replace(/^(---\r?\n)/, `$1date: ${createdMatch[1].trim()}\n`);
}
// Bridge layout -> layouts/post.njk so Obsidian notes render with the blog theme and CSS
const hasLayout = /^layout:\s*.+$/m.test(normalized);
if (!hasLayout) {
normalized = normalized.replace(/^(---\r?\n)/, "$1layout: layouts/post.njk\n");
}
// 1. Convert internal attachments: ![[image.png|alt]] or ![[image.png]]
normalized = normalized.replace(/!\[\[([^|\]]+)(?:\|([^\]]+))?\]\]/g, (match, filename, alt) => {
const cleanFilename = path.basename(filename.trim());
const altText = alt ? alt.trim() : cleanFilename;
return `![${altText}](/assets/images/posts/${cleanFilename})`;
});
// 2. Convert wikilinks with label: [[target-slug|Custom Label]] -> [Custom Label](/posts/target-slug/)
normalized = normalized.replace(/\[\[([^|\]]+)\|([^\]]+)\]\]/g, (match, target, label) => {
return `[${label.trim()}](${wikilinkUrl(target)})`;
});
// 3. Convert simple wikilinks: [[target-slug]] -> [target-slug](/posts/target-slug/)
normalized = normalized.replace(/\[\[([^\]]+)\]\]/g, (match, target) => {
const trimmed = target.trim();
return `[${trimmed}](${wikilinkUrl(trimmed)})`;
});
return normalized;
}
function wikilinkUrl(target) {
const trimmed = target.trim();
const fragmentIndex = trimmed.indexOf("#");
if (fragmentIndex === -1) {
return `/posts/${slugify(trimmed)}/`;
}
const noteSlug = slugify(trimmed.slice(0, fragmentIndex));
const headerSlug = slugify(trimmed.slice(fragmentIndex + 1));
const fragment = headerSlug ? `#${headerSlug}` : "";
return `/posts/${noteSlug}/${fragment}`;
}
function slugify(text) {
return text
.toLowerCase()
.trim()
.replace(/[^\w\s-]/g, "")
.replace(/[\s_-]+/g, "-")
.replace(/^-+|-+$/g, "");
}
let isBuilding = false;
let buildQueued = false;
/**
* Rebuilds the static site using Eleventy.
* Uses a build queue to prevent concurrent build races.
* @returns {Promise<void>}
*/
export function triggerEleventyBuild() {
if (isBuilding) {
buildQueued = true;
return Promise.resolve();
}
const root = process.cwd();
const hasConfig = fs.existsSync(path.join(root, "eleventy.config.js")) ||
fs.existsSync(path.join(root, ".eleventy.js")) ||
fs.existsSync(path.join(root, "node_modules/@11ty/eleventy"));
if (!hasConfig) {
return Promise.resolve();
}
isBuilding = true;
return new Promise((resolve) => {
exec("npx @11ty/eleventy", (err) => {
isBuilding = false;
if (err) {
console.error("[Ingestion API] Eleventy build error:", err);
} else {
console.log("[Ingestion API] Eleventy build completed successfully.");
}
if (buildQueued) {
buildQueued = false;
triggerEleventyBuild().then(resolve);
} else {
resolve();
}
});
});
}
/**
* Creates the HTTP server instance for serving static files and handling ingestion API
* @param {string} [customSiteDir] Optional custom directory for _site
* @param {string} [customPostsDir] Optional custom directory for posts
* @param {string} [customAssetsDir] Optional custom directory for uploaded post assets
* @returns {http.Server}
*/
export function createServer(customSiteDir, customPostsDir, customAssetsDir) {
const siteDir = path.resolve(customSiteDir || path.join(process.cwd(), "_site"));
const postsDir = path.resolve(customPostsDir || path.join(process.cwd(), "src/posts"));
const assetsDir = path.resolve(customAssetsDir || path.join(process.cwd(), "src/assets/images/posts"));
const isCustomEnv = Boolean(customSiteDir || customPostsDir || customAssetsDir);
// Ensure default directory data file exists for layout inheritance
try {
if (!fs.existsSync(postsDir)) {
fs.mkdirSync(postsDir, { recursive: true });
}
const postsJsonPath = path.join(postsDir, "posts.json");
if (!fs.existsSync(postsJsonPath)) {
fs.writeFileSync(postsJsonPath, JSON.stringify({ layout: "layouts/post.njk" }, null, 2));
}
} catch (err) {
console.warn("[Server] Could not initialize posts.json directory data file:", err.message);
}
return http.createServer(async (req, res) => {
// Standard security headers
res.setHeader("X-Content-Type-Options", "nosniff");
res.setHeader("X-Frame-Options", "DENY");
res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
const parsedUrl = new URL(req.url, "http://localhost");
// Health check endpoint for container orchestrators & telemetry
if (parsedUrl.pathname === "/healthz" || parsedUrl.pathname === "/health") {
res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
res.end(JSON.stringify({ status: "ok", uptime: process.uptime() }));
return;
}
// Obsidian Ingestion API: /api/posts
if (parsedUrl.pathname === "/api/posts") {
const authHeader = req.headers["authorization"] || "";
const expectedSecret = process.env.API_SECRET;
if (!expectedSecret) {
res.writeHead(500, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Server API_SECRET is not configured" }));
return;
}
const match = authHeader.match(/^Bearer\s+(.+)$/i);
if (!match || match[1] !== expectedSecret) {
res.writeHead(401, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Unauthorized: Invalid or missing Bearer token" }));
return;
}
if (req.method === "POST") {
let body = "";
req.on("data", (chunk) => {
body += chunk;
if (body.length > 50 * 1024 * 1024) {
res.writeHead(413, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Payload too large (50MB limit)" }));
req.destroy();
}
});
req.on("end", async () => {
let payload;
try {
payload = JSON.parse(body);
} catch {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Invalid JSON payload" }));
return;
}
const { slug, content, assets } = payload;
if (!slug || typeof slug !== "string" || !content || typeof content !== "string") {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Missing required fields: 'slug' and 'content'" }));
return;
}
const cleanSlug = slug.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
if (!cleanSlug) {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Invalid slug format" }));
return;
}
const hasTitle = /^title:\s*.+$/m.test(content);
const hasDate = /^date:\s*.+$/m.test(content) || /^created:\s*.+$/m.test(content);
if (!hasTitle || !hasDate) {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Missing required frontmatter: 'title' and 'created' (or 'date') are required" }));
return;
}
try {
fs.mkdirSync(postsDir, { recursive: true });
fs.mkdirSync(assetsDir, { recursive: true });
const normalizedContent = normalizeObsidianMarkdown(content);
const targetFilePath = path.join(postsDir, `${cleanSlug}.md`);
fs.writeFileSync(targetFilePath, normalizedContent, "utf-8");
if (Array.isArray(assets)) {
for (const asset of assets) {
if (asset && asset.filename && asset.data) {
const cleanName = path.basename(asset.filename).replace(/[^a-zA-Z0-9._-]/g, "");
if (cleanName) {
const assetPath = path.join(assetsDir, cleanName);
fs.writeFileSync(assetPath, Buffer.from(asset.data, "base64"));
}
}
}
}
// Rebuild static site with Eleventy if in standard environment
if (!isCustomEnv) {
await triggerEleventyBuild();
}
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({
status: "published",
slug: cleanSlug,
path: `/posts/${cleanSlug}/`
}));
} catch (writeErr) {
console.error("[Ingestion API] Error saving post/assets:", writeErr);
res.writeHead(500, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: `Failed to write file to disk: ${writeErr.message}` }));
}
});
return;
}
if (req.method === "DELETE") {
const querySlug = parsedUrl.searchParams.get("slug");
if (!querySlug) {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Missing 'slug' parameter" }));
return;
}
const cleanSlug = querySlug.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
if (!cleanSlug) {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Invalid slug parameter" }));
return;
}
// 1. Remove source markdown post
const targetFilePath = path.join(postsDir, `${cleanSlug}.md`);
if (fs.existsSync(targetFilePath)) {
fs.unlinkSync(targetFilePath);
}
// 2. Remove compiled static site directory and file
const compiledDir = path.join(siteDir, "posts", cleanSlug);
if (fs.existsSync(compiledDir)) {
fs.rmSync(compiledDir, { recursive: true, force: true });
}
const compiledHtml = path.join(siteDir, "posts", `${cleanSlug}.html`);
if (fs.existsSync(compiledHtml)) {
fs.unlinkSync(compiledHtml);
}
// 3. Rebuild static collections (index.html, dispatches, tags) with Eleventy
if (!isCustomEnv) {
await triggerEleventyBuild();
}
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ status: "deleted", slug: cleanSlug }));
return;
}
res.writeHead(405, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Method Not Allowed" }));
return;
}
// Path normalization & security validation against directory traversal
let decodedPath = "";
try {
decodedPath = decodeURIComponent(parsedUrl.pathname);
} catch {
res.writeHead(400, { "Content-Type": "text/plain" });
res.end("Bad Request");
return;
}
const resolvedPath = path.resolve(siteDir, `.${decodedPath}`);
// Boundary check: ensure target path is within siteDir
if (!resolvedPath.startsWith(siteDir)) {
res.writeHead(403, { "Content-Type": "text/plain" });
res.end("Forbidden");
return;
}
let targetFile = resolvedPath;
// Directory index resolution
if (fs.existsSync(targetFile) && fs.statSync(targetFile).isDirectory()) {
targetFile = path.join(targetFile, "index.html");
}
// Clean URL extensionless fallback (/posts/my-post -> /posts/my-post.html)
if (!fs.existsSync(targetFile) && fs.existsSync(`${targetFile}.html`)) {
targetFile = `${targetFile}.html`;
}
// Check if target file exists and is a regular file
if (fs.existsSync(targetFile) && fs.statSync(targetFile).isFile()) {
const ext = path.extname(targetFile).toLowerCase();
const contentType = MIME_TYPES[ext] || "application/octet-stream";
// Cache control: static media and webfonts get long-term caching; CSS, JS, and HTML get short revalidation
if (decodedPath.startsWith("/assets/") && !decodedPath.endsWith(".css") && !decodedPath.endsWith(".js")) {
res.setHeader("Cache-Control", "public, max-age=2592000, immutable");
} else {
res.setHeader("Cache-Control", "public, max-age=0, must-revalidate");
}
res.writeHead(200, { "Content-Type": contentType });
const stream = fs.createReadStream(targetFile);
stream.pipe(res);
return;
}
// 404 Not Found fallback
const custom404 = path.join(siteDir, "404.html");
if (fs.existsSync(custom404)) {
res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
fs.createReadStream(custom404).pipe(res);
} else {
res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
res.end("404 Not Found");
}
});
}
// Direct CLI execution handler
const currentFilePath = fileURLToPath(import.meta.url);
if (process.argv[1] && path.resolve(process.argv[1]) === currentFilePath) {
const port = parseInt(process.env.PORT || "8080", 10);
const host = process.env.HOST || "0.0.0.0";
const siteDir = path.resolve(process.cwd(), "_site");
if (!fs.existsSync(siteDir)) {
console.warn(`[Static Server] Warning: '${siteDir}' does not exist yet. Run 'npm run build' first.`);
}
const server = createServer();
server.listen(port, host, () => {
console.log(`[Static Server] Serving '${siteDir}' on http://${host}:${port}`);
});
// Graceful termination handling
const shutdown = (signal) => {
console.log(`\n[Static Server] Received ${signal}. Shutting down gracefully...`);
server.close(() => {
process.exit(0);
});
};
process.on("SIGINT", () => shutdown("SIGINT"));
process.on("SIGTERM", () => shutdown("SIGTERM"));
}
src/404.njk
-25
View File
@@ -1,25 +0,0 @@
---
layout: layouts/base.njk
permalink: /404.html
title: Page not found | River Rooks
excerpt: The requested page could not be found.
---
<section class="not-found tile" aria-labelledby="not-found-title">
<header class="tile-header">
<span class="tile-title">// ROUTE STATUS</span>
<span class="tile-meta">HTTP 404 &bull; NOT FOUND</span>
</header>
<div class="not-found-body">
<h1 class="not-found-code" id="not-found-title">404<span class="not-found-cursor" aria-hidden="true">_</span></h1>
<div class="not-found-message">
<p class="not-found-label">REQUEST FAILED / NO MATCHING ROUTE</p>
<h2>Page not found.</h2>
<p>The address you requested doesn't point to a page here. Check the URL, or choose a known route below.</p>
<nav class="not-found-links" aria-label="Recovery links">
<a href="/">&gt; Back to home</a>
<a href="/dispatches/">&gt; Browse dispatches</a>
</nav>
</div>
</div>
</section>
src/_data/site.js
-130
View File
@@ -1,130 +0,0 @@
import fs from "node:fs";
import path from "node:path";
// Load .env variables into process.env if SITE_DOMAIN is not already defined
if (!process.env.SITE_DOMAIN) {
try {
const envPath = path.resolve(process.cwd(), ".env");
if (fs.existsSync(envPath)) {
const envContent = fs.readFileSync(envPath, "utf-8");
for (const line of envContent.split("\n")) {
const trimmed = line.trim();
if (trimmed && !trimmed.startsWith("#") && trimmed.includes("=")) {
const [key, ...vals] = trimmed.split("=");
const value = vals.join("=").trim().replace(/^["']|["']$/g, "");
if (!process.env[key.trim()]) {
process.env[key.trim()] = value;
}
}
}
}
} catch (e) {
// Silent fallback
}
}
const siteDomain = process.env.SITE_DOMAIN;
if (!siteDomain) {
throw new Error(
"\n=======================================================================\n" +
"FATAL CONFIGURATION ERROR: SITE_DOMAIN environment variable is not set.\n" +
"The site domain must be explicitly defined in your .env file or environment.\n" +
"Example in .env:\n" +
" SITE_DOMAIN=riverrooks.dev\n" +
"=======================================================================\n"
);
}
const siteUrl = process.env.SITE_URL || `https://${siteDomain}`;
export default {
domain: siteDomain,
url: siteUrl,
name: "River Rooks",
title: "River Rooks | Homelab Gateway",
description: "CTF Writeups, Techincal Publucations, Homelab Journey, and Development Projects.",
status: "SYSTEMS NOMINAL",
author: "River Rooks",
nav: [
{
label: "Home",
url: "/"
},
{
label: "Dispatches",
url: "/dispatches/"
},
{
label: "Code",
url: `https://git.riverrooks.dev/venus`,
external: true
},
// {
// label: "RSS Feed",
// url: "/feed.xml"
// }
],
services: [
{
name: "Gitea",
url: `https://git.riverrooks.dev/venus`,
tag: `git.${siteDomain}:443`,
desc: "Self-hosted Git code repositories."
},
// {
// name: "CyberChef",
// url: `https://chef.${siteDomain}`,
// tag: `chef.${siteDomain}:443`,
// desc: "Industry tool for analyzing and decoding data."
// },
// {
// name: "Aperisolve",
// url: `https://aperisolve.${siteDomain}`,
// tag: `aperisolve.${siteDomain}:443`,
// desc: "Basic image steganography suite."
// },
{
name: "Streams",
url: `https://streams.${siteDomain}`,
tag: `streams.${siteDomain}:443`,
desc: "Self-hosted Steam aggregator for wathing live sports."
},
{
name: "Calibre",
url: `https://books.${siteDomain}`,
tag: `books.${siteDomain}:443`,
desc: `Calibre web frontend for managing and reading eBooks.`
},
{
name: "Wireguard",
url: `https://wg.${siteDomain}`,
tag: `wg.${siteDomain}:443`,
desc: `Self-hosted Wireguard VPN server.(Requires login)`
}
// {
// name: "Whoami",
// url: `https://whoami.${siteDomain}`,
// tag: `whoami.${siteDomain}:443`,
// desc: `Simple service to display request headers and connection information.`
// }
],
topics: [
{
title: "Systems Engineering",
slug: "systems",
desc: "Notes from my Journey building out interconnected systems.",
badge: "TRACK: SYSTEMS"
},
{
title: "Security Research",
slug: "security",
desc: "Notes from my CTF training and security research.",
badge: "TRACK: SECURITY"
},
{
title: "Homelab Infrastructure",
slug: "homelab",
desc: "Notes from building out my homelab.",
badge: "TRACK: INFRA"
}
]
};
src/_filters/index.js
-116
View File
@@ -1,116 +0,0 @@
import { DateTime } from "luxon";
import markdownIt from "markdown-it";
import { resolveLinkedArticles } from "../_utils/linked-articles.js";
/**
* Custom Eleventy Filters for River Rooks Blog
*/
const excerptMarkdown = markdownIt({ html: false });
export const renderExcerptMarkdown = (excerpt) => {
if (typeof excerpt !== "string") return "";
return excerptMarkdown.renderInline(excerpt);
};
export const postDate = (dateObj) => {
if (!dateObj) return "";
const date = typeof dateObj === "string" ? new Date(dateObj) : dateObj;
const dt = DateTime.fromJSDate(date, { zone: "utc" });
if (!dt.isValid) return "";
return dt.toFormat("LLL dd, yyyy").toUpperCase();
};
export const isoDate = (dateObj) => {
if (!dateObj) return "";
const date = typeof dateObj === "string" ? new Date(dateObj) : dateObj;
const dt = DateTime.fromJSDate(date, { zone: "utc" });
if (!dt.isValid) return "";
return dt.toISODate() || "";
};
export const limit = (arr, count) => {
if (!Array.isArray(arr)) return [];
if (count <= 0) return [];
return arr.slice(0, count);
};
export const filterTagList = (tags) => {
const internalTags = ["all", "nav", "post", "posts"];
if (!tags) return [];
const tagArray = Array.isArray(tags) ? tags : [tags];
return tagArray.filter((tag) => {
if (typeof tag !== "string") return false;
const clean = tag.replace(/^#/, "").toLowerCase();
return !internalTags.includes(clean);
});
};
export const readingTime = (text, frontmatterTime) => {
if (frontmatterTime) return frontmatterTime;
if (!text || typeof text !== "string") return "1 MIN READ";
const clean = text.replace(/<[^>]+>/g, "").trim();
if (!clean) return "1 MIN READ";
const words = clean.split(/\s+/).filter(Boolean).length;
const minutes = Math.max(1, Math.ceil(words / 200));
return `${minutes} MIN READ`;
};
export const extractHeadings = (htmlContent) => {
if (!htmlContent || typeof htmlContent !== "string") return [];
const headingRegex = /<h([23])\s+id="([^"]+)"[^>]*>(.*?)<\/h\1>/gis;
const headings = [];
let match;
while ((match = headingRegex.exec(htmlContent)) !== null) {
headings.push({
level: parseInt(match[1], 10),
id: match[2],
title: match[3].replace(/<[^>]+>/g, "").trim()
});
}
return headings;
};
const leadingTerminalPreviewHeading = /^\s*<h1\b[^>]*\bid=(["'])terminal-preview\1[^>]*>[\s\S]*?<\/h1>/i;
const terminalPreviewBounds = (htmlContent) => {
if (!htmlContent || typeof htmlContent !== "string") return null;
const heading = htmlContent.match(leadingTerminalPreviewHeading);
if (!heading) return null;
const contentAfterHeading = htmlContent.slice(heading[0].length);
const nextArticleHeading = contentAfterHeading.search(/<h[1-6]\b/i);
if (nextArticleHeading === -1) return null;
const leadingArticleWhitespace = contentAfterHeading
.slice(0, nextArticleHeading)
.match(/\s*$/)?.[0] || "";
return {
preview: contentAfterHeading.slice(0, nextArticleHeading),
article: leadingArticleWhitespace + contentAfterHeading.slice(nextArticleHeading)
};
};
export const extractTerminalPreview = (htmlContent) => terminalPreviewBounds(htmlContent)?.preview || "";
export const removeTerminalPreview = (htmlContent) => {
if (!htmlContent || typeof htmlContent !== "string") return "";
return terminalPreviewBounds(htmlContent)?.article || htmlContent;
};
export const filters = {
renderExcerptMarkdown,
postDate,
isoDate,
limit,
filterTagList,
readingTime,
extractHeadings,
extractTerminalPreview,
removeTerminalPreview,
resolveLinkedArticles
};
export default filters;
src/_includes/layouts/base.njk
-34
View File
@@ -1,34 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title | default(site.title) }}</title>
<meta name="description" content="{{ excerpt | default(site.description) }}">
<!-- Webfonts: IBM Plex Mono, JetBrains Mono, Inter -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,700;1,400&family=Inter:ital,wght@0,400;0,500;0,700;1,400&family=JetBrains+Mono:ital,wght@0,400;0,500;1,400&display=swap" rel="stylesheet">
<!-- Modular Bundled Stylesheet -->
<link rel="stylesheet" href="/assets/css/main.css?v=1.1">
{% block head %}{% endblock %}
</head>
<body>
<div class="tiling-layout">
{% include "partials/global-bar.njk" %}
<main id="main-content">
{% block content %}
{{ content | safe }}
{% endblock %}
</main>
{% include "partials/footer.njk" %}
</div>
{% block scripts %}{% endblock %}
</body>
</html>
src/_includes/layouts/page.njk
-7
View File
@@ -1,7 +0,0 @@
{% extends "layouts/base.njk" %}
{% block content %}
<div class="page-container">
{{ content | safe }}
</div>
{% endblock %}
src/_includes/layouts/post.njk
-117
View File
@@ -1,117 +0,0 @@
{% extends "layouts/base.njk" %}
{% block head %}
{% if hidden and hidden != "false" and hidden != "0" and hidden != "no" %}
<meta name="robots" content="noindex, nofollow">
{% endif %}
{% endblock %}
{% block content %}
<div class="article-workspace-grid">
<!-- Left Sticky Sidebar: Document Outline & Telemetry -->
<aside class="article-sidebar" aria-label="Article Sidebar">
<!-- Dynamic Table of Contents -->
{% set headings = (content | removeTerminalPreview) | extractHeadings %}
{% if headings.length > 0 %}
<div class="sidebar-tile">
<div class="sidebar-heading">
<span>DOCUMENT OUTLINE</span>
<span style="color: var(--accent-cyan);">[{{ headings.length }}]</span>
</div>
<nav class="toc-nav" aria-label="Table of Contents">
{% for h in headings %}
<a href="#{{ h.id }}" class="toc-link {% if h.level == 3 %}toc-sub{% endif %}">
{{ h.title }}
</a>
{% endfor %}
</nav>
</div>
{% endif %}
<!-- Article Telemetry Tile -->
<div class="sidebar-tile">
<div class="sidebar-heading">DISPATCH TELEMETRY</div>
{% set linkedPosts = collections.posts | resolveLinkedArticles(linkedArticles) %}
{% if linkedPosts.length > 0 %}
<section aria-labelledby="other-articles-heading">
<div id="other-articles-heading" class="sidebar-heading">OTHER ARTICLES</div>
<nav class="toc-nav" aria-label="Other Articles">
{% for linkedPost in linkedPosts %}
<a href="{{ linkedPost.url }}" class="toc-link">{{ linkedPost.data.title }}</a>
{% endfor %}
</nav>
</section>
{% endif %}
<div class="sidebar-stats-box" style="padding: 0; background: transparent; border: none;">
{% if hidden and hidden != "false" and hidden != "0" and hidden != "no" %}
<div class="stat-row">
<span>VISIBILITY:</span>
<span class="stat-val" style="color: var(--accent-amber);">UNLISTED</span>
</div>
{% endif %}
<div class="stat-row">
<span>PUBLISHED:</span>
<span class="stat-val">{{ date | postDate }}</span>
</div>
<div class="stat-row">
<span>DURATION:</span>
<span class="stat-val">{{ (content | removeTerminalPreview) | readingTime(readingTime) }}</span>
</div>
{% if difficulty %}
<div class="stat-row">
<span>DIFFICULTY:</span>
<span class="stat-val" style="color: var(--accent-amber);">{{ difficulty }}</span>
</div>
{% endif %}
</div>
<div style="padding-top: 10px; border-top: var(--border-width) solid var(--border-color);">
<div style="font-family: var(--font-mono); font-size: 0.72rem; color: var(--text-muted); margin-bottom: 6px;">TOPIC TAGS:</div>
<div class="tag-cluster">
{% for tag in tags | filterTagList %}
<span class="tag-chip">#{{ tag }}</span>
{% endfor %}
</div>
</div>
<div style="padding-top: 10px; border-top: var(--border-width) solid var(--border-color);">
<a href="/dispatches/" class="filter-tag-btn" style="width: 100%; justify-content: center;">
&larr; Return to Dispatches
</a>
</div>
</div>
</aside>
<!-- Right Main Article Workspace -->
<article class="article-tile" aria-labelledby="article-title">
<header class="article-header-block">
<nav class="article-breadcrumbs" aria-label="Breadcrumb">
<a href="/dispatches/">~/NOTES</a>
<span>/</span>
<span>{{ (tags | filterTagList)[0] | default('DISPATCHES') | upper }}</span>
<span>/</span>
<span style="color: var(--accent-cyan);">{{ page.fileSlug | upper }}.MD</span>
</nav>
<h1 id="article-title" class="article-main-title">{{ title }}</h1>
<div class="article-meta-row">
<span class="meta-item">
<time datetime="{{ date | isoDate }}">{{ date | postDate }}</time>
</span>
<span>&bull;</span>
<span class="meta-item">{{ (content | removeTerminalPreview) | readingTime(readingTime) }}</span>
{% if difficulty %}
<span>&bull;</span>
<span class="meta-item" style="color: var(--accent-amber);">DIFFICULTY: {{ difficulty }}</span>
{% endif %}
</div>
</header>
<div class="markdown-prose">
{{ content | removeTerminalPreview | safe }}
</div>
</article>
</div>
{% endblock %}
src/_includes/macros/tile.njk
-30
View File
@@ -1,30 +0,0 @@
{#
Reusable Tile Container Macro (macros/tile.njk)
Renders a terminal pane with header, title, meta pill, and custom body slot.
Usage:
{% import "macros/tile.njk" as ui %}
{% call ui.tile(title="STATISTICS", meta="STATIC HTML") %}
<p>Inside tile</p>
{% endcall %}
#}
{% macro tile(title="", meta="", class="", id="") %}
<section class="tile {{ class }}" {% if id %}id="{{ id }}"{% endif %}>
{% if title or meta %}
<header class="tile-header">
{% if title %}
<div class="tile-title">
<span class="status-indicator"></span>
{{ title }}
</div>
{% endif %}
{% if meta %}
<span class="tile-meta">{{ meta }}</span>
{% endif %}
</header>
{% endif %}
<div class="tile-content">
{{ caller() }}
</div>
</section>
{% endmacro %}
src/_includes/partials/featured-card.njk
-63
View File
@@ -1,63 +0,0 @@
{% set featured = null %}
{% for p in collections.posts %}
{% if p.data.featured and not featured %}
{% set featured = p %}
{% endif %}
{% endfor %}
{% if not featured and collections.posts.length > 0 %}
{% set featured = collections.posts[0] %}
{% endif %}
{% if featured %}
<section class="tile" aria-label="Featured Technical Dispatch">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
FEATURED DISPATCH
</div>
<span class="tile-meta">{{ (featured.data.tags | filterTagList)[0] | default('SYSTEMS') | upper }} &bull; {{ featured.templateContent | readingTime(featured.data.readingTime) }}</span>
</header>
<div class="featured-card-body">
<div class="featured-badge-row">
<span class="badge-pinned">[FEATURED DEEP DIVE]</span>
<time datetime="{{ featured.date | isoDate }}">{{ featured.date | postDate }}</time>
</div>
<h2 style="margin: 0; font-size: inherit;">
<a href="{{ featured.url }}" class="featured-article-title">{{ featured.data.title }}</a>
</h2>
<p class="featured-prose">
{{ featured.data.excerpt | renderExcerptMarkdown | safe }}
</p>
{% if featured.data.terminal == true %}
{% set terminalPreview = featured.templateContent | extractTerminalPreview %}
{% if terminalPreview %}
<div class="terminal-code-box terminal-preview-box">
<div class="code-titlebar">
<span class="code-title">
<span style="color: var(--accent-cyan);">&gt;</span>
<span>TERMINAL PREVIEW</span>
</span>
<span>MARKDOWN</span>
</div>
<div class="terminal-preview-content">
{{ terminalPreview | safe }}
</div>
</div>
{% endif %}
{% endif %}
<div class="featured-cta-row">
<div class="tag-cluster">
{% for tag in featured.data.tags | filterTagList %}
<span class="tag-chip">#{{ tag }}</span>
{% endfor %}
</div>
<a href="{{ featured.url }}" class="cta-button">READ FULL WRITEUP &rarr;</a>
</div>
</div>
</section>
{% endif %}
src/_includes/partials/footer.njk
-13
View File
@@ -1,13 +0,0 @@
<footer class="footer-tile" aria-label="Global Footer">
<div class="footer-left">
<span class="status-indicator"></span>
<span>RUNTIME: ELEVENTY 3.x STATIC</span>
<span>&bull;</span>
<span>THEME: NATIVE TERMINAL DARK</span>
</div>
<div class="footer-right">
<span>&copy; {{ currentYear or "2026" }} {{ site.author }}</span>
<a href="https://git.{{ site.domain }}" target="_blank" rel="noopener noreferrer" class="footer-link">Source Code ↗</a>
</div>
</footer>
src/_includes/partials/global-bar.njk
-16
View File
@@ -1,16 +0,0 @@
<header class="global-bar">
<a href="/" class="brand-group" aria-label="{{ site.name }} Home">
<span class="status-indicator"></span>
<span>{{ site.name }}</span>
</a>
<nav class="bar-nav" aria-label="Quick Navigation">
{% for item in site.nav %}
<a href="{{ item.url }}"
class="bar-link {% if item.external %}external{% endif %} {% if page.url == item.url or (item.url != '/' and page.url.startsWith(item.url)) %}active{% endif %}"
{% if item.external %}target="_blank" rel="noopener noreferrer"{% endif %}>
{% if page.url == item.url %}&gt; {% endif %}{{ item.label }}
</a>
{% endfor %}
</nav>
</header>
src/_includes/partials/hero-tile.njk
-24
View File
@@ -1,24 +0,0 @@
<section class="hero-tile" aria-label="Blog Mission & Overview">
<div class="hero-pretitle">TECHNICAL PUBLICATION REPOSITORY &bull; ~/NOTES/INDEX.MD</div>
<h1 class="hero-main-title">{{ heroTitle or site.description }}</h1>
<p class="hero-landing-text">
{{ heroText or "Notes from my Journey building out interconnected systems." }}
</p>
<div class="filter-pills-row" aria-label="Topic Filters">
<a href="/dispatches/" class="filter-tag-btn {% if not currentTag %}active{% endif %}">
[All Dispatches ({{ collections.posts.length }})]
</a>
{% for tag in collections.tagList %}
{% set tagCount = 0 %}
{% for post in collections.posts %}
{% if tag in (post.data.tags or []) %}
{% set tagCount = tagCount + 1 %}
{% endif %}
{% endfor %}
<span class="filter-tag-btn {% if currentTag == tag %}active{% endif %}">
[#{{ tag }}{% if tagCount > 0 %} ({{ tagCount }}){% endif %}]
</span>
{% endfor %}
</div>
</section>
src/_includes/partials/post-card.njk
-27
View File
@@ -1,27 +0,0 @@
<article class="feed-card" aria-labelledby="post-title-{{ post.fileSlug }}">
<div class="feed-meta-row">
<time class="feed-date" datetime="{{ post.date | isoDate }}">
{{ post.date | postDate }}
</time>
<span>{{ post.templateContent | readingTime(post.data.readingTime) }}</span>
</div>
<h3 id="post-title-{{ post.fileSlug }}">
<a href="{{ post.url }}" class="feed-heading">{{ post.data.title }}</a>
</h3>
{% if post.data.excerpt %}
<p class="feed-excerpt">{{ post.data.excerpt | renderExcerptMarkdown | safe }}</p>
{% endif %}
<div class="feed-tags-row">
<div class="tag-cluster">
{% for tag in post.data.tags | filterTagList %}
<span class="tag-chip">#{{ tag }}</span>
{% endfor %}
</div>
{% if post.data.difficulty %}
<span>DIFFICULTY: {{ post.data.difficulty }}</span>
{% endif %}
</div>
</article>
src/_includes/partials/stats-sidebar.njk
-54
View File
@@ -1,54 +0,0 @@
<aside aria-label="Archive Statistics & Topics" style="display: flex; flex-direction: column; gap: var(--tile-gap);">
<!-- Archive Statistics Tile -->
<section class="tile" aria-label="Archive Telemetry">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
ARCHIVE TELEMETRY
</div>
<span class="tile-meta">STATIC HTML</span>
</header>
<div class="sidebar-stats-box">
<div class="stat-row">
<span>TOTAL DISPATCHES:</span>
<span class="stat-val">{{ collections.posts.length }} PUBLISHED</span>
</div>
<div class="stat-row">
<span>TOPIC DOMAINS:</span>
<span class="stat-val">{{ collections.tagList.length }} CATEGORIES</span>
</div>
<div class="stat-row">
<span>CORE SPECIFICATION:</span>
<span class="stat-val">{{ site.systemSpec }}</span>
</div>
<div class="stat-row">
<span>OPERATIONAL STATUS:</span>
<span class="stat-val" style="color: var(--accent-green);">{{ site.status }}</span>
</div>
</div>
</section>
<!-- Curated Topic Tracks Tile -->
<section class="tile" aria-label="Curated Topic Tracks">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
TOPIC TRACKS
</div>
<span class="tile-meta">CURATED PATHS</span>
</header>
<div class="tile-content">
{% for topic in site.topics %}
<div class="topic-track-item">
<div style="display: flex; justify-content: space-between; align-items: baseline;">
<span class="topic-track-title">{{ topic.title }}</span>
<span style="font-family: var(--font-mono); font-size: 0.68rem; color: var(--accent-cyan);">{{ topic.badge }}</span>
</div>
<p class="topic-track-desc">{{ topic.desc }}</p>
</div>
{% endfor %}
</div>
</section>
</aside>
src/_utils/linked-articles.js
-48
View File
@@ -1,48 +0,0 @@
export const validateLinkedArticles = (posts) => {
const titles = new Set(posts.map((post) => post.data.title));
for (const post of posts) {
const { linkedArticles } = post.data;
if (linkedArticles === undefined) continue;
if (!Array.isArray(linkedArticles)) {
throw new Error(
`Post '${post.inputPath}' must define 'linkedArticles' as a YAML list of article titles`
);
}
const linkedTitleSet = new Set();
for (const title of linkedArticles) {
if (typeof title !== "string" || title.trim() === "") {
throw new Error(
`Post '${post.inputPath}' must define 'linkedArticles' with non-empty article titles`
);
}
if (title === post.data.title) {
throw new Error(`Post '${post.inputPath}' cannot link to itself`);
}
if (linkedTitleSet.has(title)) {
throw new Error(
`Post '${post.inputPath}' cannot contain duplicate article titles in 'linkedArticles'`
);
}
linkedTitleSet.add(title);
if (!titles.has(title)) {
throw new Error(
`Post '${post.inputPath}' links to unknown article '${title}'`
);
}
}
}
};
export const resolveLinkedArticles = (posts, titles) => {
if (!Array.isArray(posts) || !Array.isArray(titles)) return [];
const postsByTitle = new Map(posts.map((post) => [post.data.title, post]));
return titles.map((title) => postsByTitle.get(title)).filter(Boolean);
};
src/_utils/sort-posts.js
-117
View File
@@ -1,117 +0,0 @@
/**
* Safely extracts a numeric timestamp from an Eleventy item or its frontmatter data.
* @param {object} item Eleventy page / post object
* @returns {number} Unix timestamp in ms
*/
export function getPostTimestamp(item) {
if (!item || typeof item !== "object") return 0;
const rawDate = item.date ?? item.data?.date ?? item.data?.created;
if (rawDate instanceof Date) {
const t = rawDate.getTime();
return Number.isNaN(t) ? 0 : t;
}
if (typeof rawDate === "string" || typeof rawDate === "number") {
const t = new Date(rawDate).getTime();
return Number.isNaN(t) ? 0 : t;
}
return 0;
}
/**
* Determines whether a post is flagged as pinned or featured.
* Explicit boolean true or truthy values are supported;
* missing, null, or false values return false.
*
* @param {object} item Eleventy page / post object
* @returns {boolean}
*/
export function isPostPinned(item) {
if (!item || typeof item !== "object") return false;
const data = item.data;
if (!data || typeof data !== "object") return false;
return Boolean(data.pinned || data.featured);
}
/**
* Comparator for sorting blog posts:
* 1. Pinned or featured posts are prioritized at the top of the collection.
* 2. Within the same priority group (both pinned or both unpinned), posts
* are sorted chronologically in descending order (newest first).
*
* @param {object} a First post
* @param {object} b Second post
* @returns {number} Negative if a comes before b, positive if b comes before a, 0 if equal
*/
export function postComparator(a, b) {
const aPinned = isPostPinned(a);
const bPinned = isPostPinned(b);
if (aPinned !== bPinned) {
return bPinned ? 1 : -1;
}
const timeA = getPostTimestamp(a);
const timeB = getPostTimestamp(b);
return timeB - timeA;
}
/**
* Determines whether a post is marked as hidden.
* Hidden posts are accessible via direct link/URL, but excluded
* from public post lists, indexes, and tag collections.
* Supports explicit boolean, string ("true", "yes", "1"), or numeric representations.
*
* @param {object} item Eleventy page / post object
* @returns {boolean}
*/
export function isPostHidden(item) {
if (!item || typeof item !== "object") return false;
const data = item.data ?? item;
if (!data || typeof data !== "object") return false;
const hidden = data.hidden;
if (typeof hidden === "string") {
const lower = hidden.trim().toLowerCase();
return lower === "true" || lower === "yes" || lower === "1";
}
if (typeof hidden === "number") {
return hidden === 1;
}
return Boolean(hidden);
}
/**
* Determines whether a post is marked as a draft.
*
* @param {object} item Eleventy page / post object
* @returns {boolean}
*/
export function isPostDraft(item) {
if (!item || typeof item !== "object") return false;
const data = item.data ?? item;
if (!data || typeof data !== "object") return false;
const draft = data.draft;
if (typeof draft === "string") {
const lower = draft.trim().toLowerCase();
return lower === "true" || lower === "yes" || lower === "1";
}
if (typeof draft === "number") {
return draft === 1;
}
return Boolean(draft);
}
/**
* Determines whether a post is eligible for public collections and listings.
* A post must be non-draft and non-hidden.
*
* @param {object} item Eleventy page / post object
* @returns {boolean}
*/
export function isPostPublic(item) {
if (!item || typeof item !== "object") return false;
return !isPostDraft(item) && !isPostHidden(item);
}
export default postComparator;
src/assets/css/components/article.css
-317
View File
@@ -1,317 +0,0 @@
/* ==========================================================================
Article Workspace & Markdown Prose (components/article.css)
========================================================================== */
/* Left Sticky Sidebar (Sticky on multi-column desktop, natural flow on mobile/single-column) */
.article-sidebar {
display: flex;
flex-direction: column;
gap: var(--tile-gap);
position: static;
}
@media (min-width: 961px) {
.article-sidebar {
position: sticky;
top: 16px;
max-height: calc(100vh - 32px);
overflow-y: auto;
scrollbar-width: thin;
scrollbar-color: var(--border-color) transparent;
}
}
@media (max-width: 960px) {
.article-sidebar {
position: static !important;
top: auto !important;
max-height: none !important;
overflow: visible !important;
}
}
.sidebar-tile {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius);
padding: 18px;
display: flex;
flex-direction: column;
gap: 12px;
}
.sidebar-heading {
font-family: var(--font-mono);
font-size: 0.82rem;
font-weight: 700;
color: var(--text-muted);
text-transform: uppercase;
letter-spacing: 0.05em;
border-bottom: var(--border-width) solid var(--border-color);
padding-bottom: 8px;
display: flex;
justify-content: space-between;
align-items: center;
}
/* Document Table of Contents */
.toc-nav {
display: flex;
flex-direction: column;
gap: 4px;
font-family: var(--font-mono);
font-size: 0.78rem;
}
.toc-link {
color: var(--text-muted);
text-decoration: none;
padding: 4px 6px;
border-radius: var(--border-radius-sm);
line-height: 1.4;
display: block;
}
.toc-link:hover {
background-color: var(--bg-elevated);
color: var(--accent-cyan);
}
.toc-link.active {
color: var(--accent-cyan);
background-color: var(--bg-canvas);
border-left: 2px solid var(--accent-cyan);
font-weight: 700;
}
.toc-sub {
padding-left: 16px;
color: var(--text-muted);
font-size: 0.74rem;
}
/* Main Article Reading Container */
.article-tile {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius);
padding: 36px 40px;
display: flex;
flex-direction: column;
gap: 24px;
}
@media (max-width: 600px) {
.article-tile {
padding: 24px 18px;
}
}
/* Article Header */
.article-header-block {
border-bottom: var(--border-width) solid var(--border-color);
padding-bottom: 24px;
display: flex;
flex-direction: column;
gap: 12px;
}
.article-breadcrumbs {
font-family: var(--font-mono);
font-size: 0.78rem;
color: var(--text-muted);
display: flex;
align-items: center;
gap: 8px;
}
.article-breadcrumbs a {
color: var(--text-muted);
text-decoration: none;
}
.article-breadcrumbs a:hover {
color: var(--accent-cyan);
}
.article-main-title {
font-family: var(--font-mono);
font-size: 2.2rem;
font-weight: 700;
color: var(--text-primary);
letter-spacing: -0.02em;
line-height: 1.25;
}
@media (max-width: 768px) {
.article-main-title {
font-size: 1.7rem;
}
}
.article-meta-row {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 14px;
font-family: var(--font-mono);
font-size: 0.8rem;
color: var(--text-muted);
}
.meta-item {
display: flex;
align-items: center;
gap: 6px;
}
/* Markdown Prose Hierarchy */
.markdown-prose {
max-width: var(--prose-max-width);
font-size: 1.02rem;
color: var(--text-primary);
line-height: 1.7;
}
.markdown-prose p {
margin-bottom: 18px;
}
.markdown-prose h2 {
font-family: var(--font-mono);
font-size: 1.45rem;
font-weight: 700;
color: var(--text-primary);
margin: 36px 0 16px 0;
padding-bottom: 8px;
border-bottom: var(--border-width) solid var(--border-color);
letter-spacing: -0.01em;
}
.markdown-prose h3 {
font-family: var(--font-mono);
font-size: 1.15rem;
font-weight: 700;
color: var(--text-primary);
margin: 28px 0 12px 0;
}
.markdown-prose a {
color: var(--accent-cyan);
text-decoration: underline;
text-underline-offset: 3px;
}
.markdown-prose a:hover {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
text-decoration: none;
}
/* Inline Code */
.markdown-prose code:not(pre code) {
font-family: var(--font-code);
font-size: 0.88rem;
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
padding: 2px 6px;
border-radius: var(--border-radius-xs);
color: var(--accent-cyan);
}
/* Keyboard Shortcut Hints */
kbd {
font-family: var(--font-mono);
font-size: 0.78rem;
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
padding: 2px 6px;
border-radius: var(--border-radius-xs);
color: var(--text-primary);
box-shadow: none;
}
/* Markdown Callouts */
.markdown-callout {
margin: 20px 0;
padding: 14px 18px;
border-radius: var(--border-radius-sm);
border: var(--border-width) solid var(--border-color);
background-color: var(--bg-canvas);
font-size: 0.94rem;
line-height: 1.6;
}
.callout-note {
border-left: 4px solid var(--accent-cyan);
}
.callout-warning {
border-left: 4px solid var(--accent-amber);
}
.callout-title {
font-family: var(--font-mono);
font-weight: 700;
font-size: 0.82rem;
margin-bottom: 6px;
display: flex;
align-items: center;
gap: 6px;
}
.callout-note .callout-title {
color: var(--accent-cyan);
}
.callout-warning .callout-title {
color: var(--accent-amber);
}
/* Monospace Tables */
.table-container {
width: 100%;
overflow-x: auto;
margin: 22px 0;
}
.markdown-prose table,
.markdown-table {
width: 100%;
border-collapse: collapse;
font-size: 0.86rem;
font-family: var(--font-mono);
text-align: left;
margin: 20px 0;
border: var(--border-width) solid var(--border-color);
}
.markdown-prose th,
.markdown-table th {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
padding: 8px 12px;
color: var(--text-muted);
font-weight: 700;
}
.markdown-prose td,
.markdown-table td {
border: var(--border-width) solid var(--border-color);
padding: 8px 12px;
color: var(--text-primary);
}
.markdown-prose tr:hover,
.markdown-table tr:hover {
background-color: var(--bg-elevated);
}
/* Lists */
.markdown-prose ul, .markdown-prose ol {
margin: 16px 0 18px 24px;
}
.markdown-prose li {
margin-bottom: 6px;
}
src/assets/css/components/cards.css
-366
View File
@@ -1,366 +0,0 @@
/* ==========================================================================
Cards & Feeds (components/cards.css)
========================================================================== */
/* Featured Lead Article Card (Inside Tile) */
.featured-card-body {
display: flex;
flex-direction: column;
gap: 12px;
}
.featured-badge-row {
display: flex;
justify-content: space-between;
align-items: center;
font-family: var(--font-mono);
font-size: 0.76rem;
flex-wrap: wrap;
gap: 8px;
}
.badge-pinned {
color: var(--accent-amber);
font-weight: 700;
}
.featured-article-title {
font-family: var(--font-mono);
font-size: 1.35rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
line-height: 1.3;
}
.featured-article-title:hover {
color: var(--accent-cyan);
}
.featured-prose {
font-size: 0.92rem;
color: var(--text-primary);
line-height: 1.6;
}
.featured-cta-row {
display: flex;
justify-content: space-between;
align-items: center;
padding-top: 10px;
border-top: var(--border-width) solid var(--border-color);
flex-wrap: wrap;
gap: 10px;
font-family: var(--font-mono);
}
.cta-button {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
padding: 6px 14px;
font-weight: 700;
font-size: 0.8rem;
text-decoration: none;
border-radius: var(--border-radius-sm);
border: var(--border-width) solid var(--accent-cyan);
display: inline-block;
}
.cta-button:hover {
background-color: transparent;
color: var(--accent-cyan);
}
/* Sidebar Stats / Telemetry Box */
.sidebar-stats-box {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 12px 14px;
display: flex;
flex-direction: column;
gap: 8px;
font-family: var(--font-mono);
font-size: 0.78rem;
color: var(--text-muted);
}
.stat-row {
display: flex;
justify-content: space-between;
}
.stat-val {
color: var(--text-primary);
font-weight: 700;
}
/* Curated Topic Track Item */
.topic-track-item {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 10px 12px;
display: flex;
flex-direction: column;
gap: 4px;
text-decoration: none;
}
.topic-track-item:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.topic-track-title {
font-family: var(--font-mono);
font-size: 0.84rem;
font-weight: 700;
color: var(--text-primary);
}
.topic-track-item:hover .topic-track-title {
color: var(--accent-cyan);
}
.topic-track-desc {
font-size: 0.78rem;
color: var(--text-muted);
line-height: 1.4;
}
/* Full-Width Chronological Article Feed */
.feed-list {
display: flex;
flex-direction: column;
gap: 12px;
}
.feed-card {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 16px 18px;
display: flex;
flex-direction: column;
gap: 8px;
text-decoration: none;
}
.feed-card:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.feed-meta-row {
display: flex;
justify-content: space-between;
align-items: center;
font-family: var(--font-mono);
font-size: 0.76rem;
color: var(--text-muted);
}
.feed-date {
color: var(--accent-cyan);
}
.feed-heading {
font-family: var(--font-mono);
font-size: 1.1rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
line-height: 1.35;
}
.feed-card:hover .feed-heading {
color: var(--accent-cyan);
}
.feed-excerpt {
font-size: 0.9rem;
color: var(--text-primary);
line-height: 1.6;
}
.feed-tags-row {
display: flex;
justify-content: space-between;
align-items: center;
padding-top: 6px;
border-top: var(--border-width) solid var(--border-color);
font-family: var(--font-mono);
font-size: 0.74rem;
color: var(--text-muted);
flex-wrap: wrap;
gap: 6px;
}
.tag-cluster {
display: flex;
flex-wrap: wrap;
gap: 8px;
}
.tag-chip {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
padding: 2px 6px;
border-radius: var(--border-radius-sm);
color: var(--text-muted);
text-decoration: none;
font-family: var(--font-mono);
font-size: 0.74rem;
}
.tag-chip:hover {
border-color: var(--accent-cyan);
color: var(--accent-cyan);
}
/* Featured Service Card (Homelab Gateway) */
.blog-service-feature {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 16px;
display: flex;
flex-direction: column;
gap: 10px;
}
.blog-feature-top {
display: flex;
justify-content: space-between;
align-items: center;
font-family: var(--font-mono);
font-size: 0.78rem;
}
.badge-core {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
padding: 2px 6px;
font-weight: 700;
border-radius: var(--border-radius-sm);
}
.blog-feature-title {
font-family: var(--font-mono);
font-size: 1.15rem;
font-weight: 700;
color: var(--text-primary);
text-decoration: none;
display: inline-block;
}
.blog-feature-title:hover {
color: var(--accent-cyan);
}
.blog-feature-desc {
font-size: 0.9rem;
color: var(--text-primary);
line-height: 1.5;
}
.blog-sublinks {
display: flex;
flex-direction: column;
gap: 6px;
margin-top: 4px;
border-top: var(--border-width) solid var(--border-color);
padding-top: 10px;
}
.blog-sublink-item {
display: flex;
justify-content: space-between;
font-family: var(--font-mono);
font-size: 0.8rem;
color: var(--text-primary);
text-decoration: none;
padding: 4px 6px;
border-radius: var(--border-radius-sm);
}
.blog-sublink-item:hover {
background-color: var(--bg-elevated);
color: var(--accent-cyan);
}
/* Homelab Services Mini-Grid */
.services-mini-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 10px;
}
@media (max-width: 540px) {
.services-mini-grid {
grid-template-columns: 1fr;
}
}
.service-tile-item {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 12px;
text-decoration: none;
display: flex;
flex-direction: column;
justify-content: space-between;
gap: 6px;
}
.service-tile-item:hover {
border-color: var(--accent-cyan);
background-color: var(--bg-elevated);
}
.service-item-title {
font-family: var(--font-mono);
font-size: 0.88rem;
font-weight: 700;
color: var(--text-primary);
}
.service-tile-item:hover .service-item-title {
color: var(--accent-cyan);
}
.service-item-tag {
font-family: var(--font-mono);
font-size: 0.7rem;
color: var(--text-muted);
}
.service-item-desc {
font-size: 0.8rem;
color: var(--text-muted);
line-height: 1.4;
}
/* Infrastructure Node Telemetry */
.node-stat-row {
display: flex;
justify-content: space-between;
align-items: center;
padding: 8px 10px;
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
font-family: var(--font-mono);
font-size: 0.78rem;
}
.node-name {
color: var(--text-primary);
font-weight: 700;
}
.node-load {
color: var(--accent-green);
}
src/assets/css/components/code-box.css
-152
View File
@@ -1,152 +0,0 @@
/* ==========================================================================
Terminal Code Blocks & Syntax Highlighting (components/code-box.css)
========================================================================== */
/* Terminal Code Box Component */
.terminal-code-box,
.code-block-container {
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
background-color: var(--bg-canvas);
overflow: hidden;
font-family: var(--font-code);
margin: 18px 0;
}
.code-titlebar,
.code-block-header {
background-color: var(--bg-surface);
border-bottom: var(--border-width) solid var(--border-color);
padding: 6px 14px;
font-size: 0.74rem;
font-family: var(--font-mono);
color: var(--text-muted);
display: flex;
justify-content: space-between;
align-items: center;
}
.code-title {
display: flex;
align-items: center;
gap: 8px;
color: var(--text-primary);
font-weight: 500;
}
.copy-code-btn {
background: transparent;
border: var(--border-width) solid var(--border-color);
color: var(--text-muted);
padding: 2px 8px;
font-family: inherit;
font-size: 0.72rem;
cursor: pointer;
border-radius: var(--border-radius-sm);
}
.copy-code-btn:hover {
border-color: var(--accent-cyan);
color: var(--accent-cyan);
}
.code-content,
.code-block-container pre,
.markdown-prose pre {
padding: 14px 16px;
font-size: 0.82rem;
overflow-x: auto;
color: var(--text-primary);
line-height: 1.55;
margin: 18px 0;
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
font-family: var(--font-code);
}
.terminal-preview-box {
margin: 0;
}
.terminal-preview-content {
padding: 14px 16px;
color: var(--text-primary);
font-size: 0.82rem;
line-height: 1.55;
}
.terminal-preview-content > :first-child {
margin-top: 0;
}
.terminal-preview-content > :last-child {
margin-bottom: 0;
}
.terminal-preview-content pre {
margin: 10px 0;
padding: 10px 12px;
overflow-x: auto;
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
font-family: var(--font-code);
}
/* Syntax Highlighting Tokens (Prism / 11ty Syntax Highlight) */
.token.comment,
.token.prolog,
.token.doctype,
.token.cdata {
color: #5c6370;
font-style: italic;
}
.token.punctuation {
color: #abb2bf;
}
.token.property,
.token.tag,
.token.boolean,
.token.number,
.token.constant,
.token.symbol,
.token.deleted {
color: var(--accent-amber);
}
.token.selector,
.token.attr-name,
.token.string,
.token.char,
.token.builtin,
.token.inserted {
color: var(--accent-green);
}
.token.operator,
.token.entity,
.token.url,
.language-css .token.string,
.style .token.string {
color: var(--accent-cyan);
}
.token.atrule,
.token.attr-value,
.token.keyword {
color: #c678dd;
}
.token.function,
.token.class-name {
color: #61afef;
}
.token.regex,
.token.important,
.token.variable {
color: var(--accent-amber);
}
src/assets/css/components/footer.css
-39
View File
@@ -1,39 +0,0 @@
/* ==========================================================================
Footer Tile (components/footer.css)
========================================================================== */
.footer-tile {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius);
padding: 14px 20px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: var(--font-mono);
font-size: 0.74rem;
color: var(--text-muted);
flex-wrap: wrap;
gap: 12px;
}
.footer-left {
display: flex;
align-items: center;
gap: 12px;
}
.footer-right {
display: flex;
gap: 16px;
align-items: center;
}
.footer-link {
color: var(--text-muted);
text-decoration: none;
}
.footer-link:hover {
color: var(--accent-cyan);
}
src/assets/css/components/global-bar.css
-63
View File
@@ -1,63 +0,0 @@
/* ==========================================================================
Global Status Header Bar (components/global-bar.css)
========================================================================== */
.global-bar {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius);
padding: 10px 18px;
display: flex;
justify-content: space-between;
align-items: center;
font-family: var(--font-mono);
font-size: 0.8rem;
flex-wrap: wrap;
gap: 10px;
}
.brand-group {
display: flex;
align-items: center;
gap: 10px;
color: var(--text-primary);
font-weight: 700;
text-decoration: none;
}
.brand-group:hover {
color: var(--accent-cyan);
}
.status-indicator {
width: 8px;
height: 8px;
background-color: var(--accent-green);
display: inline-block;
}
.bar-nav {
display: flex;
gap: 14px;
align-items: center;
}
.bar-link {
color: var(--text-muted);
text-decoration: none;
}
.bar-link:hover {
color: var(--accent-cyan);
}
.bar-link.active {
color: var(--text-primary);
border-bottom: 1px solid var(--accent-cyan);
}
.bar-link.external::after {
content: " ↗";
font-size: 0.75em;
color: var(--text-muted);
}
src/assets/css/components/not-found.css
-86
View File
@@ -1,86 +0,0 @@
/* Missing route: a compact diagnostic panel in the site's tiling vocabulary. */
.not-found {
gap: 0;
padding: 20px 24px 28px;
}
.not-found-body {
display: grid;
grid-template-columns: minmax(0, 0.8fr) minmax(0, 1fr);
align-items: center;
gap: 24px;
min-height: 320px;
}
.not-found-code {
font-family: var(--font-mono);
font-size: clamp(5rem, 14vw, 10rem);
line-height: 1;
letter-spacing: -0.09em;
color: var(--accent-amber);
white-space: nowrap;
}
.not-found-cursor {
color: var(--text-muted);
}
.not-found-message {
border-left: 1px solid var(--border-color);
padding: 16px 0 16px 24px;
max-width: 48ch;
}
.not-found-label {
font: 500 0.75rem var(--font-mono);
letter-spacing: 0.06em;
color: var(--accent-amber);
margin-bottom: 12px;
}
.not-found-message h2 {
font: 700 clamp(1.3rem, 3vw, 2rem) / 1.25 var(--font-mono);
margin-bottom: 12px;
}
.not-found-message > p:not(.not-found-label) {
color: var(--text-muted);
max-width: 42ch;
}
.not-found-links {
display: flex;
flex-wrap: wrap;
gap: 8px 24px;
margin-top: 24px;
font: 500 0.85rem var(--font-mono);
}
.not-found-links a {
color: var(--accent-cyan);
text-decoration: none;
}
.not-found-links a:hover {
color: var(--bg-canvas);
background: var(--accent-cyan);
}
@media (max-width: 680px) {
.not-found {
padding: 16px;
}
.not-found-body {
grid-template-columns: 1fr;
gap: 8px;
min-height: 0;
padding: 32px 0 8px;
}
.not-found-message {
border-left: 0;
border-top: 1px solid var(--border-color);
padding: 20px 0 0;
}
}
src/assets/css/components/tiles.css
-141
View File
@@ -1,141 +0,0 @@
/* ==========================================================================
Tile Containers & Hero Tile (components/tiles.css)
========================================================================== */
/* Standard Tile Container */
.tile {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius);
padding: 20px;
display: flex;
flex-direction: column;
gap: 14px;
}
.tile-header {
display: flex;
justify-content: space-between;
align-items: baseline;
border-bottom: var(--border-width) solid var(--border-color);
padding-bottom: 10px;
flex-wrap: wrap;
gap: 8px;
}
.tile-title {
font-family: var(--font-mono);
font-size: 0.92rem;
font-weight: 700;
color: var(--text-primary);
display: flex;
align-items: center;
gap: 8px;
}
.tile-meta {
font-family: var(--font-mono);
font-size: 0.74rem;
color: var(--text-muted);
}
.tile-content {
display: flex;
flex-direction: column;
gap: 12px;
}
/* Hero Lander Tile */
.hero-tile {
background-color: var(--bg-surface);
border: var(--border-width) solid var(--border-color);
border-left: 3px solid var(--accent-cyan);
border-radius: var(--border-radius);
padding: 24px 28px;
display: flex;
flex-direction: column;
gap: 12px;
margin-bottom: 16px;
}
.hero-pretitle {
font-family: var(--font-mono);
font-size: 0.8rem;
color: var(--accent-cyan);
letter-spacing: 0.06em;
text-transform: uppercase;
}
.hero-main-title {
font-family: var(--font-mono);
font-size: 2.1rem;
font-weight: 700;
color: var(--text-primary);
letter-spacing: -0.02em;
line-height: 1.2;
}
@media (max-width: 600px) {
.hero-main-title {
font-size: 1.6rem;
}
}
.hero-landing-text {
font-size: 0.98rem;
color: var(--text-primary);
line-height: 1.65;
max-width: 82ch;
}
/* Filter Pills Row in Hero Tile */
.filter-pills-row {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 8px;
margin-top: 4px;
font-family: var(--font-mono);
font-size: 0.78rem;
}
.filter-tag-btn {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
color: var(--text-muted);
padding: 3px 8px;
border-radius: var(--border-radius-sm);
cursor: pointer;
text-decoration: none;
display: inline-flex;
align-items: center;
}
.filter-tag-btn:hover {
border-color: var(--accent-cyan);
color: var(--text-primary);
background-color: var(--bg-elevated);
}
.filter-tag-btn.active {
background-color: var(--accent-cyan);
color: var(--bg-canvas);
border-color: var(--accent-cyan);
font-weight: 700;
}
/* Directive Callout Box inside Hero */
.hero-directive-box {
background-color: var(--bg-canvas);
border: var(--border-width) solid var(--border-color);
border-radius: var(--border-radius-sm);
padding: 12px 16px;
font-family: var(--font-mono);
font-size: 0.82rem;
color: var(--text-muted);
line-height: 1.6;
}
.hero-directive-box strong {
color: var(--text-primary);
}
src/assets/css/layout.css
-53
View File
@@ -1,53 +0,0 @@
/* ==========================================================================
Tiling Window Manager Grids & Layout (layout.css)
========================================================================== */
/* Outer Shell Container */
.tiling-layout {
width: 100%;
max-width: var(--site-max-width);
display: flex;
flex-direction: column;
gap: var(--tile-gap);
}
/* Asymmetric 2-Column Split Grid (Lander: Lead Article + Telemetry Sidebar) */
.split-grid {
display: grid;
grid-template-columns: 1.25fr 0.75fr;
gap: var(--tile-gap);
align-items: start;
}
@media (max-width: 880px) {
.split-grid {
grid-template-columns: 1fr;
}
}
/* Article Workspace Grid (Left Sidebar TOC + Main Reading Workspace) */
.article-workspace-grid {
display: grid;
grid-template-columns: 290px 1fr;
gap: var(--tile-gap);
align-items: start;
}
@media (max-width: 960px) {
.article-workspace-grid {
grid-template-columns: 1fr;
}
}
/* Generic Symmetrical Grids */
.grid-2col {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: var(--tile-gap);
}
@media (max-width: 768px) {
.grid-2col {
grid-template-columns: 1fr;
}
}
src/assets/css/main.css
-22
View File
@@ -1,22 +0,0 @@
/* ==========================================================================
Main Stylesheet (main.css)
River Rooks Blog - Modular CSS Architecture
========================================================================== */
/* 1. Design Tokens & CSS Custom Properties */
@import "./tokens.css";
/* 2. Global Reset & Baseline Typography */
@import "./reset.css";
/* 3. Tiling Window Manager Grids */
@import "./layout.css";
/* 4. Component Styles */
@import "./components/global-bar.css";
@import "./components/tiles.css";
@import "./components/cards.css";
@import "./components/code-box.css";
@import "./components/article.css";
@import "./components/footer.css";
@import "./components/not-found.css";
src/assets/css/reset.css
-52
View File
@@ -1,52 +0,0 @@
/* ==========================================================================
CSS Reset & Baseline (reset.css)
Strict adherence to developer-centric minimalism & instant transitions
========================================================================== */
*, *::before, *::after {
box-sizing: border-box;
margin: 0;
padding: 0;
}
html {
font-size: 16px;
-webkit-text-size-adjust: 100%;
text-rendering: optimizeLegibility;
scroll-behavior: smooth;
}
body {
background-color: var(--bg-canvas);
color: var(--text-primary);
font-family: var(--font-prose);
line-height: 1.6;
min-height: 100vh;
display: flex;
flex-direction: column;
align-items: center;
padding: 24px 16px 48px 16px;
overflow-x: hidden;
}
/* Hard anti-pattern enforcement: instant transitions across UI elements */
a, button, input, select, textarea {
transition: none !important;
}
/* High-contrast keyboard accessibility outline */
:focus-visible {
outline: 2px solid var(--accent-cyan);
outline-offset: 2px;
}
img, svg, video {
max-width: 100%;
height: auto;
display: block;
}
/* Monospace font assignment for code & structural elements */
code, pre, kbd, samp {
font-family: var(--font-code);
}
src/assets/css/tokens.css
-38
View File
@@ -1,38 +0,0 @@
/* ==========================================================================
Design Tokens (tokens.css)
River Rooks Blog - Native Dark Mode Architecture
========================================================================== */
:root {
/* Surface & Canvas Colors */
--bg-canvas: #0d0f12; /* Deep slate/charcoal canvas */
--bg-surface: #121417; /* Tile & card surface */
--bg-elevated: #1c1f26; /* Hovered surface */
/* Borders & Dividers */
--border-color: #2b303b; /* Crisp 1px border */
--border-width: 1px;
--border-radius: 4px; /* Strictly capped at 4px */
--border-radius-sm: 2px;
--border-radius-xs: 1px;
/* Typography */
--font-mono: 'IBM Plex Mono', 'JetBrains Mono', monospace;
--font-code: 'JetBrains Mono', 'Fira Code', monospace;
--font-prose: 'Inter', system-ui, -apple-system, sans-serif;
/* Text Colors */
--text-primary: #e0e6f0; /* Light off-white prose */
--text-muted: #8a95a5; /* Monospace metadata */
/* High-Signal Terminal Accents */
--accent-cyan: #00f0ff; /* Primary active accent */
--accent-green: #00e676; /* Success / online indicator */
--accent-amber: #ffb700; /* Warning / highlight accent */
--accent-red: #ff5252; /* Danger / caution accent */
/* Structural Dimensions */
--site-max-width: 1140px;
--tile-gap: 16px;
--prose-max-width: 68ch;
}
src/dispatches.njk
-39
View File
@@ -1,39 +0,0 @@
---
layout: layouts/base.njk
title: "River Rooks | Engineering Notes & Systems Architecture"
---
<!-- 1. Lander Hero Tile with Dynamic Filter Tag Buttons -->
{% include "partials/hero-tile.njk" %}
<!-- 2. Asymmetric Split Grid: Featured Lead Post (Left) & Telemetry Sidebar (Right) -->
<div class="split-grid">
<div class="split-lead-col">
{% include "partials/featured-card.njk" %}
</div>
<div class="split-sidebar-col">
{% include "partials/stats-sidebar.njk" %}
</div>
</div>
<!-- 3. Full-Width Chronological Dispatches Feed Tile -->
<section class="tile" aria-label="Dispatches Feed Catalog">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
RECENT DISPATCHES
</div>
<span class="tile-meta">ORDER: CHRONOLOGICAL DESC &bull; TOTAL: {{ collections.posts.length }}</span>
</header>
<div class="feed-list">
{% for post in collections.posts %}
{% include "partials/post-card.njk" %}
{% else %}
<p style="color: var(--text-muted); font-family: var(--font-mono); font-size: 0.85rem; padding: 16px;">
No published dispatches found in repository.
</p>
{% endfor %}
</div>
</section>
src/index.njk
-117
View File
@@ -1,117 +0,0 @@
---
layout: layouts/base.njk
title: "River Rooks | Homelab Gateway"
---
<!-- Main Hero Landing Tile -->
<section class="hero-tile" aria-label="Gateway Declaration">
<div class="hero-pretitle">SYSTEM DECLARATION &bull; NODE GATEWAY</div>
<h1 class="hero-main-title">Cybersecurity &amp; Dev Ops notes</h1>
<div class="hero-landing-text">
<p>
I am River Rooks, a cyber security student at the University of Alabama. This website is the public-facing gateway to my homelab, which hosts a variety of services and tools for personal and professional use. Here, you can find my technical blog and a collection of public tools that host.
</p>
<p>
I deploy and maintain a variety of services in my homelab for research, development, and learning purposes. This includes web applications, databases, and other tools that I use to enhance my skills in cybersecurity and DevOps.
</p>
<p>
My blog serves as a way to share some of my extensive notes with the public. I primarily focus on Capture The Flag (CTF) writeups, technical guides, and other cybersecurity-related content. I also use this platform to document my learning journey and share insights into the world of cybersecurity and DevOps.
</div>
<div class="hero-directive-box">
<strong>PRIMARY DESTINATIONS:</strong>
<a href="/dispatches/" style="color: var(--accent-cyan); text-decoration: none; margin-left: 8px;">[1] Technical Blog ({{ collections.posts.length }} Articles)</a> &bull;
<a href="https://git.{{ site.domain }}" target="_blank" rel="noopener noreferrer" style="color: inherit; text-decoration: none;">[2] Gitea Repos</a> &bull;
<a href="https://github.com/skoorrevir" target="_blank" rel="noopener noreferrer" style="color: inherit; text-decoration: none;">[3] GitHub Repos</a> &bull;
<a href="https://wg.{{ site.domain }}" target="_blank" rel="noopener noreferrer" style="color: inherit; text-decoration: none;">[4] Wireguard VPN</a> &bull;
</div>
</section>
<!-- Split Tiling Columns -->
<div class="split-grid">
<!-- Left Column: Featured Service (Blog) + Dynamic Recent Articles -->
<div style="display: flex; flex-direction: column; gap: var(--tile-gap);">
<section class="tile" aria-label="Featured Service: Technical Blog">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
// PRIMARY SERVICE: THE TECHNICAL BLOG
</div>
<span class="tile-meta">~/notes/ &bull; {{ collections.posts.length }} ARTICLES</span>
</header>
<div class="blog-service-feature">
<div class="blog-feature-top">
<span class="badge-core">[CORE PUBLICATION SERVICE]</span>
<span style="color: var(--text-muted);">{{ collections.posts[0].date | postDate }} LAST SYNC</span>
</div>
<a href="/dispatches/" class="blog-feature-title">&gt; Technical Notes &amp; Engineering Dispatches</a>
<p class="blog-feature-desc">
Notes from my Journey building out interconnected systems.
</p>
<div class="blog-sublinks">
{% for post in collections.posts | limit(4) %}
<a href="{{ post.url }}" class="blog-sublink-item">
<span>{{ loop.index }}. {{ post.data.title }}</span>
<span style="color: var(--accent-cyan);">[{{ post.templateContent | readingTime(post.data.readingTime) }}] &rarr;</span>
</a>
{% endfor %}
</div>
</div>
</section>
</div>
<!-- Right Column: Homelab Hosted Services & Node Telemetry -->
<div style="display: flex; flex-direction: column; gap: var(--tile-gap);">
<section class="tile" aria-label="Homelab Services Directory">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
// HOMELAB SERVICES ROUTER
</div>
<span class="tile-meta">{{ site.services.length }} PUBLIC TOOLS</span>
</header>
<div class="services-mini-grid">
{% for svc in site.services %}
<a href="{{ svc.url }}" target="_blank" rel="noopener noreferrer" class="service-tile-item">
<div>
<div class="service-item-title">{{ svc.name }}</div>
<div class="service-item-tag">{{ svc.tag }}</div>
</div>
<p class="service-item-desc">{{ svc.desc }}</p>
</a>
{% endfor %}
</div>
</section>
<!-- Infrastructure Telemetry Tile -->
<section class="tile" aria-label="Infrastructure Nodes Telemetry">
<header class="tile-header">
<div class="tile-title">
<span class="status-indicator"></span>
// CLUSTER TELEMETRY
</div>
<span class="tile-meta">3 NODES ONLINE</span>
</header>
<div style="display: flex; flex-direction: column; gap: 8px;">
<div class="node-stat-row">
<span class="node-name">NODE-01 (Primary Cluster)</span>
<span class="node-load">ONLINE &bull; LOAD: 0.18</span>
</div>
<div class="node-stat-row">
<span class="node-name">NODE-02 (Storage Array)</span>
<span class="node-load">ONLINE &bull; POOL: 98% HEALTH</span>
</div>
<div class="node-stat-row">
<span class="node-name">GATEWAY-01 (Edge Ingress)</span>
<span class="node-load">ONLINE &bull; ROUTING ACTIVE</span>
</div>
</div>
</section>
</div>
</div>
src/posts/posts.json
-3
View File
@@ -1,3 +0,0 @@
{
"layout": "layouts/post.njk"
}
test/build-integrity.test.js
-86
View File
@@ -1,86 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { execSync } from "node:child_process";
const siteDir = path.resolve("_site");
function getAllHtmlFiles(dir) {
let results = [];
const list = fs.readdirSync(dir);
for (const file of list) {
const filePath = path.join(dir, file);
const stat = fs.statSync(filePath);
if (stat && stat.isDirectory()) {
results = results.concat(getAllHtmlFiles(filePath));
} else if (file.endsWith(".html")) {
results.push(filePath);
}
}
return results;
}
test("Build & Link Integrity: Output inspection and link verification", () => {
// Ensure fresh build exists
if (!fs.existsSync(path.join(siteDir, "index.html"))) {
execSync("npm run build", {
stdio: "pipe",
env: { ...process.env, SITE_DOMAIN: process.env.SITE_DOMAIN || "riverrooks.dev" }
});
}
// 1. Core Pages Exist
assert.ok(fs.existsSync(path.join(siteDir, "index.html")), "Root _site/index.html must exist");
assert.ok(fs.existsSync(path.join(siteDir, "dispatches/index.html")), "_site/dispatches/index.html must exist");
assert.ok(fs.existsSync(path.join(siteDir, "assets/css/main.css")), "_site/assets/css/main.css must exist");
const htmlFiles = getAllHtmlFiles(siteDir);
assert.ok(htmlFiles.length >= 4, "Must compile all core pages and articles");
for (const htmlFile of htmlFiles) {
const relHtml = path.relative(siteDir, htmlFile);
const content = fs.readFileSync(htmlFile, "utf-8");
// 2. HTML Boilerplate Invariants
assert.match(content, /<!DOCTYPE html>/i, `${relHtml} must contain <!DOCTYPE html>`);
assert.match(content, /<meta\s+name="viewport"/i, `${relHtml} must have viewport meta tag`);
assert.match(content, /<link\s+rel="stylesheet"\s+href="\/assets\/css\/main\.css(?:\?[^"]*)?">/i, `${relHtml} must link to main.css`);
// 3. Internal Link Integrity (No 404s!)
const internalLinks = [...content.matchAll(/href="(\/[^"#?]*)"/g)].map((m) => m[1]);
for (const link of internalLinks) {
if (link.startsWith("/feed.xml")) continue; // dynamic RSS route
// Normalize link to file on disk: /dispatches/ -> _site/dispatches/index.html or _site/dispatches.html
let targetPath;
if (link.endsWith("/")) {
targetPath = path.join(siteDir, link, "index.html");
} else if (path.extname(link)) {
targetPath = path.join(siteDir, link);
} else {
targetPath = path.join(siteDir, `${link}.html`);
if (!fs.existsSync(targetPath)) {
targetPath = path.join(siteDir, link, "index.html");
}
}
assert.ok(
fs.existsSync(targetPath),
`Broken internal link in ${relHtml}: href="${link}" resolves to missing file: ${targetPath}`
);
}
// 4. Anchor Link Integrity (TOC anchor links match actual heading IDs)
const anchorLinks = [...content.matchAll(/href="#([^"]+)"/g)].map((m) => m[1]);
for (const anchor of anchorLinks) {
// Ignore skip-to-content or standard body anchors
if (anchor === "main-content") continue;
const expectedIdRegex = new RegExp(`id="${anchor}"`, "i");
assert.match(
content,
expectedIdRegex,
`Broken TOC anchor link in ${relHtml}: href="#${anchor}" has no corresponding id="${anchor}"`
);
}
}
});
test/design-rules.test.js
-86
View File
@@ -1,86 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const cssDir = path.resolve("src/assets/css");
function getAllCssFiles(dir) {
let results = [];
const list = fs.readdirSync(dir);
for (const file of list) {
const filePath = path.join(dir, file);
const stat = fs.statSync(filePath);
if (stat && stat.isDirectory()) {
results = results.concat(getAllCssFiles(filePath));
} else if (file.endsWith(".css")) {
results.push(filePath);
}
}
return results;
}
test("Design Specification: Strict Anti-Pattern Regression Testing", () => {
const cssFiles = getAllCssFiles(cssDir);
assert.ok(cssFiles.length >= 5, "Must inspect all modular CSS files");
for (const file of cssFiles) {
const relPath = path.relative(process.cwd(), file);
const content = fs.readFileSync(file, "utf-8");
// 1. Anti-Pattern: NO Glassmorphism (backdrop-filter)
assert.doesNotMatch(
content,
/backdrop-filter\s*:/i,
`Violation in ${relPath}: Glassmorphism (backdrop-filter) is strictly forbidden`
);
// 2. Anti-Pattern: NO Drop Shadows or Glows (box-shadow, text-shadow)
// Allowed: box-shadow: none; or text-shadow: none;
const shadowMatches = content.match(/(box-shadow|text-shadow)\s*:\s*([^;]+);/gi) || [];
for (const match of shadowMatches) {
assert.match(
match,
/(box-shadow|text-shadow)\s*:\s*none\s*;/i,
`Violation in ${relPath}: Drop shadows and glows are forbidden (found: '${match}')`
);
}
// 3. Anti-Pattern: NO Gradients (linear, radial, conic)
assert.doesNotMatch(
content,
/(linear-gradient|radial-gradient|conic-gradient)/i,
`Violation in ${relPath}: Gradients are strictly forbidden`
);
// 4. Anti-Pattern: NO Rounded Bubbles (border-radius capped at 4px max)
const radiusMatches = content.match(/border-radius\s*:\s*([^;]+);/gi) || [];
for (const match of radiusMatches) {
// Check for pixel values > 4px (e.g. 5px, 6px, 8px, 12px, 20px)
const pxMatch = match.match(/(\d+)\s*px/i);
if (pxMatch) {
const px = parseInt(pxMatch[1], 10);
assert.ok(
px <= 4,
`Violation in ${relPath}: Border radius must be 0px to 4px max, found: ${px}px in '${match}'`
);
}
// Check for percentages (e.g. 50%)
assert.doesNotMatch(
match,
/\d+%/,
`Violation in ${relPath}: Rounded pill/circular percentages forbidden in '${match}'`
);
}
// 5. Anti-Pattern: NO Float/Spring Transitions (Must be instant snaps)
const transitionMatches = content.match(/transition\s*:\s*([^;]+);/gi) || [];
for (const match of transitionMatches) {
assert.match(
match,
/transition\s*:\s*(none(\s*!important)?|0s\s*);/i,
`Violation in ${relPath}: Transitions must be instant (none or 0s), found: '${match}'`
);
}
}
});
test/development-standards.test.js
-112
View File
@@ -1,112 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const agentsMdPath = path.resolve("AGENTS.md");
const rulesMdPath = path.resolve(".agents/rules/blog-system.md");
test("Development Standards: AGENTS.md enforces test-first, adversarial testing, and verification gates", () => {
assert.ok(fs.existsSync(agentsMdPath), "AGENTS.md must exist in root");
const content = fs.readFileSync(agentsMdPath, "utf-8");
// 1. Must enforce writing tests BEFORE modifying functional/production code
assert.match(
content,
/before\s+(?:writing\s+or\s+)?modifying\s+(?:any\s+)?(?:functional|production)\s+code/i,
"AGENTS.md must explicitly mandate that tests are written before modifying functional/production code"
);
// 2. Must mandate adversarial testing
assert.match(
content,
/adversarial\s+test(?:ing|s)/i,
"AGENTS.md must mandate adversarial testing"
);
// 3. Must mandate that all tests pass before presenting final output
assert.match(
content,
/pass\s+before\s+presenting\s+(?:the\s+)?final\s+output/i,
"AGENTS.md must mandate that test cases pass before presenting final output"
);
});
test("Development Standards: .agents/rules/blog-system.md enforces test-first, adversarial testing, and verification gates", () => {
assert.ok(fs.existsSync(rulesMdPath), ".agents/rules/blog-system.md must exist");
const content = fs.readFileSync(rulesMdPath, "utf-8");
// 1. Must enforce writing tests BEFORE modifying functional/production code
assert.match(
content,
/before\s+(?:writing\s+or\s+)?modifying\s+(?:any\s+)?(?:functional|production)\s+code/i,
"blog-system.md must explicitly mandate that tests are written before modifying functional/production code"
);
// 2. Must mandate adversarial testing
assert.match(
content,
/adversarial\s+test(?:ing|s)/i,
"blog-system.md must mandate adversarial testing"
);
// 3. Must mandate that all tests pass before presenting final output
assert.match(
content,
/pass\s+before\s+presenting\s+(?:the\s+)?final\s+output/i,
"blog-system.md must mandate that test cases pass before presenting final output"
);
});
test("Development Standards: Adversarial checks against vague or permissive testing language", () => {
const files = [agentsMdPath, rulesMdPath];
for (const filePath of files) {
const content = fs.readFileSync(filePath, "utf-8");
const relPath = path.relative(process.cwd(), filePath);
// Adversarial: ensure no permissive "or alongside implementing" loophole exists
assert.doesNotMatch(
content,
/or\s+alongside\s+implementing/i,
`Violation in ${relPath}: Permissive loophole "or alongside implementing" must not exist; tests must strictly precede functional code`
);
}
});
test("Development Standards: README.md and skills reference TDD, adversarial testing, and verification", () => {
const readmePath = path.resolve("README.md");
assert.ok(fs.existsSync(readmePath), "README.md must exist");
const readmeContent = fs.readFileSync(readmePath, "utf-8");
assert.match(
readmeContent,
/written\s+before\s+(?:writing\s+or\s+)?modifying\s+(?:any\s+)?functional\s+code/i,
"README.md must document writing tests before modifying functional code"
);
assert.match(
readmeContent,
/adversarial\s+test(?:ing|s)/i,
"README.md must document mandatory adversarial testing"
);
assert.match(
readmeContent,
/pass\s+before\s+presenting\s+(?:the\s+)?final\s+output/i,
"README.md must document that tests must pass before presenting final output"
);
// Check eleventy-tiling-blog skill
const eleventySkillPath = path.resolve(".agents/skills/eleventy-tiling-blog/SKILL.md");
assert.ok(fs.existsSync(eleventySkillPath), "eleventy-tiling-blog SKILL.md must exist");
const eleventySkill = fs.readFileSync(eleventySkillPath, "utf-8");
assert.match(eleventySkill, /adversarial/i, "eleventy-tiling-blog SKILL.md must mention adversarial testing");
assert.match(eleventySkill, /before\s+modifying\s+functional/i, "eleventy-tiling-blog SKILL.md must mandate tests before modifying functional code");
// Check obsidian-sync skill
const obsidianSkillPath = path.resolve(".agents/skills/obsidian-sync/SKILL.md");
assert.ok(fs.existsSync(obsidianSkillPath), "obsidian-sync SKILL.md must exist");
const obsidianSkill = fs.readFileSync(obsidianSkillPath, "utf-8");
assert.match(obsidianSkill, /adversarial/i, "obsidian-sync SKILL.md must mention adversarial testing");
assert.match(obsidianSkill, /before[*\s`_]+modifying/i, "obsidian-sync SKILL.md must mandate tests before modifying functional code");
});
test/docker-config.test.js
-64
View File
@@ -1,64 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
test("Docker Configuration: Dockerfile enforces Node runtime, healthcheck, and entrypoint", () => {
const dockerfilePath = path.resolve(process.cwd(), "Dockerfile");
assert.ok(fs.existsSync(dockerfilePath), "Dockerfile must exist");
const content = fs.readFileSync(dockerfilePath, "utf-8");
// Must use Node 22 alpine
assert.match(content, /FROM\s+node:22-alpine/i, "Dockerfile must use node:22-alpine base image");
// Must NOT contain nginx base images or references
assert.doesNotMatch(content, /FROM\s+nginx/i, "Dockerfile must not use nginx base image");
assert.doesNotMatch(content, /nginx/i, "Dockerfile must not contain nginx directives");
// Must build static site and configure dynamic port
assert.match(content, /RUN\s+npm\s+run\s+build/, "Dockerfile must compile baseline static assets");
assert.match(content, /ARG\s+PORT=8080/, "Dockerfile must define ARG PORT with default fallback");
assert.match(content, /ENV\s+PORT=\$\{?PORT\}?/, "Dockerfile must define ENV PORT using variable");
assert.match(content, /EXPOSE\s+\$\{?PORT\}?/, "Dockerfile must expose dynamic PORT variable");
// Must define built-in HEALTHCHECK probing 127.0.0.1 loopback
assert.match(content, /HEALTHCHECK[\s\S]*?127\.0\.0\.1/, "Dockerfile must define baked-in HEALTHCHECK on 127.0.0.1");
// Must configure dynamic entrypoint script
assert.match(content, /ENTRYPOINT\s*\[\s*["']\/app\/entrypoint\.sh["']\s*\]/, "Dockerfile must use /app/entrypoint.sh entrypoint");
});
test("Docker Configuration: entrypoint.sh script exists and has valid structure", () => {
const entrypointPath = path.resolve(process.cwd(), "entrypoint.sh");
assert.ok(fs.existsSync(entrypointPath), "entrypoint.sh must exist");
const stats = fs.statSync(entrypointPath);
// Check executable permissions (at least owner executable: 0o100)
assert.ok(Boolean(stats.mode & 0o111), "entrypoint.sh must have executable permission bits");
const content = fs.readFileSync(entrypointPath, "utf-8");
assert.match(content, /^#!\/bin\/sh/, "entrypoint.sh must use POSIX /bin/sh shebang");
assert.match(content, /exec\s+"\$@"/, "entrypoint.sh must pass through custom container arguments");
assert.match(content, /npm\s+run\s+build/, "entrypoint.sh must build the static site");
assert.match(content, /exec\s+node\s+server\.js/, "entrypoint.sh must start static server with exec");
});
test("Docker Configuration: docker-compose configures Node service correctly", () => {
const composePath = fs.existsSync(path.resolve(process.cwd(), "sample-docker-compose.yml"))
? path.resolve(process.cwd(), "sample-docker-compose.yml")
: path.resolve(process.cwd(), "docker-compose.yml");
assert.ok(fs.existsSync(composePath), "Compose template file must exist");
const content = fs.readFileSync(composePath, "utf-8");
// Verifies dynamic port mapping and environment variables
assert.match(content, /PORT.*8080/, "docker-compose.yml must configure PORT fallback");
assert.match(content, /:\$\{PORT:-8080\}/, "docker-compose.yml must map dynamic container PORT");
// Verifies domain argument enforcement
assert.match(content, /SITE_DOMAIN/, "docker-compose.yml must require SITE_DOMAIN");
// Verifies markdown volume mount
assert.match(content, /\/app\/src\/posts/, "docker-compose.yml must mount external markdown posts");
});
test/excerpt-markdown-links.test.js
-64
View File
@@ -1,64 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import nunjucks from "nunjucks";
import path from "node:path";
import { filters } from "../src/_filters/index.js";
const includesDir = path.resolve("src/_includes");
const markdownExcerpt = "Read the [deployment guide](/guides/deploy/) before continuing.";
function renderTemplate(template, context) {
const env = new nunjucks.Environment(new nunjucks.FileSystemLoader(includesDir), { autoescape: false });
for (const [name, filter] of Object.entries(filters)) {
env.addFilter(name, filter);
}
return env.render(template, context);
}
test("Excerpt Markdown: renders Markdown links as safe inline HTML", () => {
assert.equal(
filters.renderExcerptMarkdown(markdownExcerpt),
'Read the <a href="/guides/deploy/">deployment guide</a> before continuing.'
);
});
test("Excerpt Markdown: renders links in post-card previews", () => {
const output = renderTemplate("partials/post-card.njk", {
post: {
fileSlug: "example-dispatch",
url: "/dispatches/example/",
date: "2026-10-06",
data: {
title: "Example dispatch",
excerpt: markdownExcerpt,
tags: ["systems"]
},
templateContent: "A short article."
}
});
assert.match(output, /<p class="feed-excerpt">\s*Read the <a href="\/guides\/deploy\/">deployment guide<\/a> before continuing\.\s*<\/p>/);
});
test("Excerpt Markdown: renders links in featured previews and escapes raw HTML", () => {
const output = renderTemplate("partials/featured-card.njk", {
collections: {
posts: [{
url: "/dispatches/example/",
date: "2026-10-06",
data: {
featured: true,
tags: ["systems"],
title: "Example dispatch",
excerpt: `${markdownExcerpt} <script>alert('unsafe')</script>`
},
templateContent: ""
}]
}
});
assert.match(output, /<a href="\/guides\/deploy\/">deployment guide<\/a>/);
assert.match(output, /&lt;script&gt;alert\('unsafe'\)&lt;\/script&gt;/);
assert.doesNotMatch(output, /<script>/);
});
test/featured-terminal-preview.test.js
-62
View File
@@ -1,62 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import nunjucks from "nunjucks";
import path from "node:path";
import {
extractTerminalPreview,
filterTagList,
isoDate,
postDate,
readingTime,
renderExcerptMarkdown
} from "../src/_filters/index.js";
const includesDir = path.resolve("src/_includes");
function renderFeaturedCard(terminal) {
const env = new nunjucks.Environment(new nunjucks.FileSystemLoader(includesDir), { autoescape: false });
env.addFilter("extractTerminalPreview", extractTerminalPreview);
env.addFilter("filterTagList", filterTagList);
env.addFilter("isoDate", isoDate);
env.addFilter("postDate", postDate);
env.addFilter("readingTime", readingTime);
env.addFilter("renderExcerptMarkdown", renderExcerptMarkdown);
const featured = {
url: "/dispatches/example/",
date: "2026-10-06",
data: {
featured: true,
terminal,
tags: ["systems"],
title: "Example dispatch",
excerpt: "An example featured dispatch used to verify the terminal preview."
},
templateContent: `
<h1 id="terminal-preview">Terminal preview</h1>
<p>Inspect the first five lines:</p>
<pre><code class="language-bash">cat /dispatches/example | head -n 5</code></pre>
<h1 id="investigation">Investigation</h1>
<p>The public article begins here.</p>
`
};
return env.render("partials/featured-card.njk", {
collections: { posts: [featured] }
});
}
test("Featured terminal preview: renders Markdown output only when terminal frontmatter is true", () => {
const output = renderFeaturedCard(true);
assert.match(output, /class="[^"]*terminal-code-box[^"]*"/);
assert.match(output, /Inspect the first five lines:/);
assert.match(output, /cat \/dispatches\/example \| head -n 5/);
assert.doesNotMatch(output, /Terminal preview/);
assert.doesNotMatch(output, /init_cluster\.sh/);
});
test("Featured terminal preview: does not render when terminal frontmatter is false or absent", () => {
assert.doesNotMatch(renderFeaturedCard(false), /terminal-code-box/);
assert.doesNotMatch(renderFeaturedCard(undefined), /terminal-code-box/);
});
test/filters.test.js
-107
View File
@@ -1,107 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import {
postDate,
isoDate,
limit,
filterTagList,
readingTime,
extractHeadings
} from "../src/_filters/index.js";
test("Filters - postDate: formats valid dates", () => {
assert.equal(postDate("2026-07-20"), "JUL 20, 2026");
assert.equal(postDate(new Date("2026-12-31T00:00:00Z")), "DEC 31, 2026");
});
test("Filters - postDate: handles adversarial / invalid inputs gracefully", () => {
assert.equal(postDate(null), "");
assert.equal(postDate(undefined), "");
assert.equal(postDate("invalid-date-string"), "");
assert.equal(postDate(""), "");
});
test("Filters - isoDate: formats ISO strings", () => {
assert.equal(isoDate("2026-07-20"), "2026-07-20");
assert.equal(isoDate(new Date("2026-05-15T00:00:00Z")), "2026-05-15");
});
test("Filters - isoDate: handles adversarial / invalid inputs gracefully", () => {
assert.equal(isoDate(null), "");
assert.equal(isoDate(undefined), "");
assert.equal(isoDate("not-a-date"), "");
});
test("Filters - limit: slices arrays correctly", () => {
assert.deepEqual(limit([1, 2, 3, 4, 5], 3), [1, 2, 3]);
assert.deepEqual(limit([1, 2], 5), [1, 2]);
});
test("Filters - limit: handles adversarial inputs (negative, 0, non-array)", () => {
assert.deepEqual(limit([1, 2, 3], 0), []);
assert.deepEqual(limit([1, 2, 3], -5), []);
assert.deepEqual(limit(null, 3), []);
assert.deepEqual(limit("not-an-array", 3), []);
});
test("Filters - filterTagList: removes internal system tags", () => {
const input = ["firmware", "posts", "security", "all", "nav", "post"];
assert.deepEqual(filterTagList(input), ["firmware", "security"]);
});
test("Filters - filterTagList: handles adversarial inputs (# prefix, casing, non-string)", () => {
const input = ["#firmware", "#POSTS", "ALL", "#homelab", 42, null, undefined];
assert.deepEqual(filterTagList(input), ["#firmware", "#homelab"]);
assert.deepEqual(filterTagList(null), []);
assert.deepEqual(filterTagList(undefined), []);
});
test("Filters - readingTime: calculates reading time from word count", () => {
// 199 words -> 1 min
const shortText = "word ".repeat(199);
assert.equal(readingTime(shortText), "1 MIN READ");
// 201 words -> 2 min
const mediumText = "word ".repeat(201);
assert.equal(readingTime(mediumText), "2 MIN READ");
// 1000 words -> 5 min
const longText = "word ".repeat(1000);
assert.equal(readingTime(longText), "5 MIN READ");
});
test("Filters - readingTime: respects explicit frontmatter override", () => {
assert.equal(readingTime("any text", "15 MIN READ"), "15 MIN READ");
});
test("Filters - readingTime: handles adversarial HTML tags without inflating word count", () => {
// HTML tags should be stripped before counting words
const htmlText = "<div><span>word</span> <p>another</p></div>";
assert.equal(readingTime(htmlText), "1 MIN READ");
assert.equal(readingTime(""), "1 MIN READ");
assert.equal(readingTime(null), "1 MIN READ");
});
test("Filters - extractHeadings: extracts H2 and H3 with IDs and titles", () => {
const html = `
<h1>Title To Ignore</h1>
<h2 id="section-1">1.0 First Section</h2>
<p>Some text</p>
<h3 id="sub-1">1.1 Sub Section</h3>
<h4 id="h4-ignore">Ignore H4</h4>
<h2 id="section-2">2.0 Second Section with <code>code</code> and <span class="tag">span</span></h2>
`;
const headings = extractHeadings(html);
assert.equal(headings.length, 3);
assert.deepEqual(headings[0], { level: 2, id: "section-1", title: "1.0 First Section" });
assert.deepEqual(headings[1], { level: 3, id: "sub-1", title: "1.1 Sub Section" });
assert.deepEqual(headings[2], { level: 2, id: "section-2", title: "2.0 Second Section with code and span" });
});
test("Filters - extractHeadings: handles adversarial HTML inputs gracefully", () => {
assert.deepEqual(extractHeadings(""), []);
assert.deepEqual(extractHeadings(null), []);
assert.deepEqual(extractHeadings(undefined), []);
assert.deepEqual(extractHeadings("<p>No headings here</p>"), []);
});
test/frontmatter-schema.test.js
-76
View File
@@ -1,76 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const postsDir = path.resolve("src/posts");
test("Content Contract: All posts in src/posts/ satisfy frontmatter schema", () => {
if (!fs.existsSync(postsDir)) {
fs.mkdirSync(postsDir, { recursive: true });
}
const postFiles = fs.readdirSync(postsDir).filter((f) => f.endsWith(".md"));
if (postFiles.length === 0) {
// When posts are decoupled and mounted externally or ingested via API
return;
}
for (const file of postFiles) {
const filePath = path.join(postsDir, file);
const content = fs.readFileSync(filePath, "utf-8");
// 1. Filename Convention: YYYY-MM-DD-slug.md
assert.match(
file,
/^\d{4}-\d{2}-\d{2}-[a-z0-9-]+\.md$/,
`Post filename '${file}' must follow 'YYYY-MM-DD-slug.md' naming standard`
);
// 2. YAML Frontmatter Boundary check
assert.match(
content,
/^---\n([\s\S]*?)\n---/,
`Post '${file}' must start with valid YAML frontmatter delimiters`
);
// Extract frontmatter block
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
const fmText = fmMatch[1];
// 3. Title Invariant
assert.match(
fmText,
/title:\s*"[^"]{5,}"/,
`Post '${file}' must contain a valid title of at least 5 characters`
);
// 4. Date Invariant (ISO Format)
assert.match(
fmText,
/date:\s*\d{4}-\d{2}-\d{2}/,
`Post '${file}' must define an ISO date (YYYY-MM-DD)`
);
// 5. Layout Invariant
assert.match(
fmText,
/layout:\s*layouts\/post\.njk/,
`Post '${file}' must specify 'layout: layouts/post.njk'`
);
// 6. Tags Invariant
assert.match(
fmText,
/tags:\s*\n(\s+-\s+[a-z0-9-]+\n)+/,
`Post '${file}' must specify a non-empty YAML tags list`
);
// 7. Excerpt Invariant
assert.match(
fmText,
/excerpt:\s*"[^"]{20,}"/,
`Post '${file}' must provide a substantive excerpt of at least 20 characters`
);
}
});
test/healthcheck.js
-5
View File
@@ -1,5 +0,0 @@
const port = process.env.PORT || 8080;
fetch(`http://127.0.0.1:${port}/healthz`)
.then((res) => process.exit(res.ok ? 0 : 1))
.catch(() => process.exit(1));
test/healthcheck.test.js
-79
View File
@@ -1,79 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import http from "node:http";
import { spawn } from "node:child_process";
test("Healthcheck: test/healthcheck.js script exists and parses cleanly", () => {
const scriptPath = path.resolve(process.cwd(), "test/healthcheck.js");
assert.ok(fs.existsSync(scriptPath), "test/healthcheck.js must exist");
const content = fs.readFileSync(scriptPath, "utf-8");
assert.match(content, /127\.0\.0\.1/, "Must target IPv4 loopback 127.0.0.1 to avoid Alpine IPv6 lookup failures");
assert.match(content, /\/healthz/, "Must target the /healthz endpoint");
});
test("Healthcheck: test/healthcheck.js succeeds when server returns 200 OK", async () => {
const scriptPath = path.resolve(process.cwd(), "test/healthcheck.js");
// Start dummy HTTP server responding 200 on /healthz
const server = http.createServer((req, res) => {
if (req.url === "/healthz") {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ status: "ok" }));
} else {
res.writeHead(404);
res.end();
}
});
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
const exitCode = await new Promise((resolve) => {
const child = spawn(process.execPath, [scriptPath], {
env: { ...process.env, PORT: String(port) },
});
child.on("close", resolve);
});
assert.strictEqual(exitCode, 0, "healthcheck.js must exit with code 0 on healthy endpoint");
} finally {
await new Promise((resolve) => server.close(resolve));
}
});
test("Healthcheck: test/healthcheck.js fails when connection is refused or server is 500", async () => {
const scriptPath = path.resolve(process.cwd(), "test/healthcheck.js");
// Pick an unused high port
const exitCodeDown = await new Promise((resolve) => {
const child = spawn(process.execPath, [scriptPath], {
env: { ...process.env, PORT: "59999" },
});
child.on("close", resolve);
});
assert.strictEqual(exitCodeDown, 1, "healthcheck.js must exit with code 1 when server is unreachable");
// Test 500 status code
const server = http.createServer((req, res) => {
res.writeHead(500);
res.end();
});
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
const exitCode500 = await new Promise((resolve) => {
const child = spawn(process.execPath, [scriptPath], {
env: { ...process.env, PORT: String(port) },
});
child.on("close", resolve);
});
assert.strictEqual(exitCode500, 1, "healthcheck.js must exit with code 1 on HTTP 500");
} finally {
await new Promise((resolve) => server.close(resolve));
}
});
test/hidden-posts.test.js
-293
View File
@@ -1,293 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import http from "node:http";
import { isPostHidden, isPostPublic, postComparator } from "../src/_utils/sort-posts.js";
import { createServer, normalizeObsidianMarkdown } from "../server.js";
test("Hidden Posts: isPostHidden accurately identifies hidden flags across data shapes", () => {
// 1. Explicit boolean true
assert.equal(isPostHidden({ data: { hidden: true } }), true, "Explicit boolean true in data");
assert.equal(isPostHidden({ hidden: true }), true, "Root level hidden true");
// 2. Truthy string representations (case-insensitive & trimmed)
assert.equal(isPostHidden({ data: { hidden: "true" } }), true, "String 'true'");
assert.equal(isPostHidden({ data: { hidden: "TRUE" } }), true, "Uppercase string 'TRUE'");
assert.equal(isPostHidden({ data: { hidden: " true " } }), true, "Whitespace-padded 'true'");
assert.equal(isPostHidden({ data: { hidden: "yes" } }), true, "String 'yes'");
assert.equal(isPostHidden({ data: { hidden: "YES" } }), true, "String 'YES'");
assert.equal(isPostHidden({ data: { hidden: "1" } }), true, "String '1'");
assert.equal(isPostHidden({ data: { hidden: 1 } }), true, "Numeric 1");
// 3. Falsy representations
assert.equal(isPostHidden({ data: { hidden: false } }), false, "Explicit boolean false");
assert.equal(isPostHidden({ data: { hidden: "false" } }), false, "String 'false'");
assert.equal(isPostHidden({ data: { hidden: "no" } }), false, "String 'no'");
assert.equal(isPostHidden({ data: { hidden: "0" } }), false, "String '0'");
assert.equal(isPostHidden({ data: { hidden: 0 } }), false, "Numeric 0");
assert.equal(isPostHidden({ data: { hidden: "" } }), false, "Empty string");
assert.equal(isPostHidden({ data: { hidden: null } }), false, "Null property");
assert.equal(isPostHidden({ data: {} }), false, "Missing hidden property");
assert.equal(isPostHidden({}), false, "Empty post object");
// 4. Adversarial edge cases
assert.equal(isPostHidden(null), false, "Null input");
assert.equal(isPostHidden(undefined), false, "Undefined input");
assert.equal(isPostHidden("unexpected-string"), false, "Primitive string input");
assert.equal(isPostHidden(12345), false, "Primitive number input");
assert.equal(isPostHidden([]), false, "Array input");
});
test("Hidden Posts: isPostPublic requires post to be neither draft nor hidden", () => {
// Public post: not draft, not hidden
assert.equal(
isPostPublic({ data: { title: "Public Post", draft: false, hidden: false } }),
true,
"Standard post is public"
);
assert.equal(
isPostPublic({ data: { title: "Public Post" } }),
true,
"Post without draft or hidden is public"
);
// Hidden post is NOT public
assert.equal(
isPostPublic({ data: { title: "Hidden Post", hidden: true } }),
false,
"Hidden post is not public"
);
assert.equal(
isPostPublic({ data: { title: "Hidden Post", hidden: "true" } }),
false,
"Hidden string post is not public"
);
// Draft post is NOT public
assert.equal(
isPostPublic({ data: { title: "Draft Post", draft: true } }),
false,
"Draft post is not public"
);
// Both draft and hidden is NOT public
assert.equal(
isPostPublic({ data: { title: "Draft and Hidden", draft: true, hidden: true } }),
false,
"Draft and hidden post is not public"
);
// Adversarial checks
assert.equal(isPostPublic(null), false, "Null is not public");
assert.equal(isPostPublic(undefined), false, "Undefined is not public");
assert.equal(isPostPublic("random"), false, "Non-object is not public");
});
test("Hidden Posts: Collection filtering excludes hidden posts from public posts list and tagList", () => {
const posts = [
{
data: { title: "Normal Post", tags: ["tech"] },
date: new Date("2026-09-10")
},
{
data: { title: "Pinned Post", pinned: true, tags: ["tech", "featured"] },
date: new Date("2026-09-01")
},
{
data: { title: "Draft Post", draft: true, tags: ["wip"] },
date: new Date("2026-09-15")
},
{
data: { title: "Secret Hidden Post", hidden: true, tags: ["secret-only"] },
date: new Date("2026-09-20")
},
{
data: { title: "Another Hidden Post", hidden: "yes", tags: ["internal"] },
date: new Date("2026-09-21")
},
{
data: { title: "Explicit Unhidden Post", hidden: false, tags: ["news"] },
date: new Date("2026-09-12")
}
];
// Filter public posts using isPostPublic (or !draft && !isPostHidden)
const publicPosts = posts.filter(isPostPublic).sort(postComparator);
const titles = publicPosts.map((p) => p.data.title);
assert.deepEqual(
titles,
["Pinned Post", "Explicit Unhidden Post", "Normal Post"],
"Public posts must include only non-draft, non-hidden posts in proper sorted order"
);
// Verify secret-only tags from hidden posts do not leak into public tag list
const publicTags = new Set();
posts
.filter(isPostPublic)
.forEach((item) => {
const tags = item.data.tags || [];
for (const t of tags) publicTags.add(t);
});
assert.ok(!publicTags.has("secret-only"), "Hidden post tag 'secret-only' must not appear in public tag list");
assert.ok(!publicTags.has("internal"), "Hidden post tag 'internal' must not appear in public tag list");
assert.ok(!publicTags.has("wip"), "Draft post tag 'wip' must not appear in public tag list");
assert.ok(publicTags.has("tech"), "Public post tag 'tech' must appear in public tag list");
assert.ok(publicTags.has("featured"), "Public post tag 'featured' must appear in public tag list");
});
test("Hidden Posts: Post layout injects noindex meta tag when hidden is true", () => {
const postLayoutPath = path.resolve("src/_includes/layouts/post.njk");
assert.ok(fs.existsSync(postLayoutPath), "post.njk must exist");
const postLayout = fs.readFileSync(postLayoutPath, "utf-8");
// Adversarial verification: hidden posts must instruct search crawlers not to index or follow
assert.match(
postLayout,
/noindex,\s*nofollow/i,
"post.njk must define 'noindex, nofollow' robots meta tag when hidden"
);
assert.match(
postLayout,
/{%\s*if\s+hidden\b/i,
"post.njk must conditionally check if post is hidden"
);
});
test("Hidden Posts: Obsidian normalization preserves hidden frontmatter property", () => {
const obsidianNote = `---
title: "Confidential System Blueprint"
created: 2026-09-23
tags: ["#architecture", "#secret"]
hidden: true
---
# Blueprint
Details for authorized eyes only.
`;
const normalized = normalizeObsidianMarkdown(obsidianNote);
assert.match(normalized, /hidden:\s*true/, "Normalized markdown must preserve 'hidden: true'");
assert.match(normalized, /title:\s*"Confidential System Blueprint"/, "Preserves title");
assert.match(normalized, /date:\s*2026-09-23/, "Bridges created to date");
assert.match(normalized, /layout:\s*layouts\/post\.njk/, "Adds post layout");
});
test("Hidden Posts: End-to-end static compilation and accessibility via direct link", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
try {
// 1. Create a public post and a hidden post
const publicPostContent = `---
title: "Public Announcement"
date: 2026-09-20
layout: layouts/post.njk
tags: ["news"]
excerpt: "This is a public announcement for everyone to read."
---
Public content visible to everyone.`;
const hiddenPostContent = `---
title: "Private Unlisted Memo"
date: 2026-09-22
layout: layouts/post.njk
tags: ["confidential"]
excerpt: "This is an unlisted memo meant for direct link access only."
hidden: true
---
Secret memo content available by link only.`;
fs.writeFileSync(path.join(tmpPosts, "2026-09-20-public-post.md"), publicPostContent, "utf-8");
fs.writeFileSync(path.join(tmpPosts, "2026-09-22-secret-memo.md"), hiddenPostContent, "utf-8");
// 2. Set up server with custom directories
process.env.API_SECRET = "test-secret";
const server = createServer(tmpDir, tmpPosts);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
// Simulate static files created by build
fs.mkdirSync(path.join(tmpDir, "posts/2026-09-22-secret-memo"), { recursive: true });
fs.mkdirSync(path.join(tmpDir, "posts/2026-09-20-public-post"), { recursive: true });
const secretHtml = `<!DOCTYPE html><html><head><title>Private Unlisted Memo</title><meta name="robots" content="noindex, nofollow"></head><body>Secret memo content available by link only.</body></html>`;
const publicHtml = `<!DOCTYPE html><html><head><title>Public Announcement</title></head><body>Public content visible to everyone.</body></html>`;
const indexHtml = `<!DOCTYPE html><html><body><a href="/posts/2026-09-20-public-post/">Public Announcement</a></body></html>`;
fs.writeFileSync(path.join(tmpDir, "posts/2026-09-22-secret-memo/index.html"), secretHtml);
fs.writeFileSync(path.join(tmpDir, "posts/2026-09-20-public-post/index.html"), publicHtml);
fs.writeFileSync(path.join(tmpDir, "index.html"), indexHtml);
// Verify direct access to hidden post succeeds (HTTP 200 OK)
const resSecret = await fetch(`http://127.0.0.1:${port}/posts/2026-09-22-secret-memo/`);
assert.strictEqual(resSecret.status, 200, "Direct link to hidden post must return 200 OK");
const secretBody = await resSecret.text();
assert.match(secretBody, /Secret memo content available by link only/, "Hidden post body is accessible");
assert.match(secretBody, /noindex,\s*nofollow/, "Hidden post includes noindex meta tag");
// Verify public index does NOT contain link or title to hidden post
const resIndex = await fetch(`http://127.0.0.1:${port}/`);
assert.strictEqual(resIndex.status, 200);
const indexBody = await resIndex.text();
assert.match(indexBody, /Public Announcement/, "Public post is listed on index");
assert.doesNotMatch(indexBody, /Private Unlisted Memo/, "Hidden post MUST NOT appear on index");
assert.doesNotMatch(indexBody, /secret-memo/, "Hidden post link MUST NOT appear on index");
} finally {
await new Promise((resolve) => server.close(resolve));
}
} finally {
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
}
});
test("Hidden Posts: Obsidian API ingestion correctly writes hidden frontmatter", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
process.env.API_SECRET = "test-secret";
const server = createServer(tmpDir, tmpPosts);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
const res = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer test-secret"
},
body: JSON.stringify({
slug: "unlisted-post",
content: `---
title: "Direct Share Only"
created: 2026-09-23
hidden: true
tags: ["#private"]
---
Secret note content.`
})
});
assert.strictEqual(res.status, 200);
const json = await res.json();
assert.strictEqual(json.status, "published");
assert.strictEqual(json.path, "/posts/unlisted-post/");
const writtenFile = path.join(tmpPosts, "unlisted-post.md");
assert.ok(fs.existsSync(writtenFile), "Post file must exist");
const writtenContent = fs.readFileSync(writtenFile, "utf-8");
assert.match(writtenContent, /hidden:\s*true/);
assert.match(writtenContent, /layout:\s*layouts\/post\.njk/);
} finally {
await new Promise((resolve) => server.close(resolve));
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
}
});
test/ingestion-api.test.js
-303
View File
@@ -1,303 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import http from "node:http";
import { createServer, normalizeObsidianMarkdown, triggerEleventyBuild } from "../server.js";
const TEST_SECRET = "super-secret-test-token";
test("Obsidian normalization: preserves linked note header fragments", () => {
const normalized = normalizeObsidianMarkdown(
"See [[a note#header one]] and [[another note#Second Header|the other section]]."
);
assert.match(
normalized,
/\[a note#header one\]\(\/posts\/a-note\/#header-one\)/,
"A wikilink header must become a URL fragment on the linked note"
);
assert.match(
normalized,
/\[the other section\]\(\/posts\/another-note\/#second-header\)/,
"Aliased wikilinks must retain their linked-note header fragment"
);
});
test("Ingestion API: rejects requests without proper Bearer token", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
process.env.API_SECRET = TEST_SECRET;
const server = createServer(tmpDir, tmpPosts);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
// 1. Missing Authorization header
const resNoAuth = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ slug: "test", content: "test" })
});
assert.strictEqual(resNoAuth.status, 401, "Missing auth header must return 401");
// 2. Invalid Bearer token
const resBadAuth = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer wrong-token"
},
body: JSON.stringify({ slug: "test", content: "test" })
});
assert.strictEqual(resBadAuth.status, 401, "Invalid token must return 401");
} finally {
await new Promise((resolve) => server.close(resolve));
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
}
});
test("Ingestion API: validates required fields and frontmatter schema", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
process.env.API_SECRET = TEST_SECRET;
const server = createServer(tmpDir, tmpPosts);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
// Missing slug
const resNoSlug = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({ content: "---\ntitle: 'Test'\ndate: 2026-09-14\n---\nHello" })
});
assert.strictEqual(resNoSlug.status, 400, "Missing slug must return 400");
// Missing required frontmatter title
const resNoTitle = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({
slug: "no-title-post",
content: "---\ndate: 2026-09-14\n---\nHello"
})
});
assert.strictEqual(resNoTitle.status, 400, "Missing frontmatter title must return 400");
// Missing required frontmatter date or created
const resNoDate = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({
slug: "no-date-post",
content: "---\ntitle: 'Valid Title'\n---\nHello"
})
});
assert.strictEqual(resNoDate.status, 400, "Missing frontmatter created/date must return 400");
// Valid with created instead of date
const resWithCreated = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({
slug: "created-tag-post",
content: "---\ntitle: 'Valid Title'\ncreated: 2026-09-14\n---\nHello"
})
});
assert.strictEqual(resWithCreated.status, 200, "Valid post with created tag must return 200");
} finally {
await new Promise((resolve) => server.close(resolve));
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
}
});
test("Ingestion API: publishes markdown, normalizes wikilinks, saves assets, and handles delete", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
const tmpAssets = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-assets-"));
process.env.API_SECRET = TEST_SECRET;
const server = createServer(tmpDir, tmpPosts, tmpAssets);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
const rawMarkdown = `---
title: "Reverse Engineering Flock Safety"
created: 2026-09-14
tags: ["#security", "#firmware"]
excerpt: "A deep dive into firmware."
---
Check out [[other-post|Other Post]] and also [[simple-link]].
Here is an image: ![[camera-board.png]]
`;
// 1x1 transparent PNG base64
const sampleBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";
try {
// Publish post
const resPublish = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({
slug: "flock-firmware",
content: rawMarkdown,
assets: [
{
filename: "camera-board.png",
data: sampleBase64
}
]
})
});
assert.strictEqual(resPublish.status, 200, "Valid publish must return 200");
const json = await resPublish.json();
assert.strictEqual(json.status, "published");
assert.strictEqual(json.path, "/posts/flock-firmware/");
// Verify markdown file written and wikilinks normalized
const writtenPath = path.join(tmpPosts, "flock-firmware.md");
assert.ok(fs.existsSync(writtenPath), "Post markdown file must be written to disk");
const writtenContent = fs.readFileSync(writtenPath, "utf-8");
assert.match(writtenContent, /^layout:\s*layouts\/post\.njk$/m, "Layout must be injected into frontmatter when missing");
assert.match(writtenContent, /\[Other Post\]\(\/posts\/other-post\/\)/, "Wikilink with alias must be translated");
assert.match(writtenContent, /\[simple-link\]\(\/posts\/simple-link\/\)/, "Simple wikilink must be translated");
assert.match(writtenContent, /!\[camera-board\.png\]\(\/assets\/images\/posts\/camera-board\.png\)/, "Attachment wikilink must be translated");
// Verify asset image was written
const assetPath = path.join(tmpAssets, "camera-board.png");
assert.ok(fs.existsSync(assetPath), "Asset file must be saved");
// Create simulated compiled static post files in siteDir
const compiledPostDir = path.join(tmpDir, "posts", "flock-firmware");
fs.mkdirSync(compiledPostDir, { recursive: true });
const compiledPostHtml = path.join(compiledPostDir, "index.html");
fs.writeFileSync(compiledPostHtml, "<html><body>Simulated compiled post</body></html>");
const standalonePostHtml = path.join(tmpDir, "posts", "flock-firmware.html");
fs.writeFileSync(standalonePostHtml, "<html><body>Simulated standalone post</body></html>");
assert.ok(fs.existsSync(compiledPostHtml), "Simulated compiled post must exist before delete");
assert.ok(fs.existsSync(standalonePostHtml), "Simulated standalone post must exist before delete");
// Delete post
const resDelete = await fetch(`http://127.0.0.1:${port}/api/posts?slug=flock-firmware`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${TEST_SECRET}`
}
});
assert.strictEqual(resDelete.status, 200, "Delete must return 200");
assert.ok(!fs.existsSync(writtenPath), "Post markdown file must be deleted");
assert.ok(!fs.existsSync(compiledPostDir), "Compiled post directory must be deleted from _site");
assert.ok(!fs.existsSync(standalonePostHtml), "Compiled standalone HTML must be deleted from _site");
} finally {
await new Promise((resolve) => server.close(resolve));
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
fs.rmSync(tmpAssets, { recursive: true, force: true });
}
});
test("Ingestion API: adversarial protection against path traversal in slug and DELETE validation", async () => {
const tmpDir = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-site-"));
const tmpPosts = fs.mkdtempSync(path.join(process.cwd(), "test-tmp-posts-"));
process.env.API_SECRET = TEST_SECRET;
const server = createServer(tmpDir, tmpPosts);
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const port = server.address().port;
try {
// 1. Path traversal in POST
const resTraversal = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${TEST_SECRET}`
},
body: JSON.stringify({
slug: "../../etc/evil",
content: "---\ntitle: 'Evil'\ndate: 2026-09-14\n---\nEvil content"
})
});
// Should sanitize or reject slug containing path traversal
if (resTraversal.status === 200) {
const evilPath = path.resolve(tmpPosts, "../../etc/evil.md");
assert.ok(!fs.existsSync(evilPath), "Must never write outside posts directory");
} else {
assert.strictEqual(resTraversal.status, 400, "Invalid slug must return 400");
}
// 2. DELETE without auth token
const resDeleteNoAuth = await fetch(`http://127.0.0.1:${port}/api/posts?slug=any-post`, {
method: "DELETE"
});
assert.strictEqual(resDeleteNoAuth.status, 401, "DELETE without Bearer token must return 401");
// 3. DELETE with missing slug parameter
const resDeleteNoSlug = await fetch(`http://127.0.0.1:${port}/api/posts`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${TEST_SECRET}`
}
});
assert.strictEqual(resDeleteNoSlug.status, 400, "DELETE without slug parameter must return 400");
// 4. DELETE with invalid/empty slug
const resDeleteBadSlug = await fetch(`http://127.0.0.1:${port}/api/posts?slug=///`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${TEST_SECRET}`
}
});
assert.strictEqual(resDeleteBadSlug.status, 400, "DELETE with invalid slug must return 400");
// 5. DELETE non-existent post succeeds gracefully (idempotent)
const resDeleteNonExistent = await fetch(`http://127.0.0.1:${port}/api/posts?slug=non-existent-post`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${TEST_SECRET}`
}
});
assert.strictEqual(resDeleteNonExistent.status, 200, "DELETE non-existent post must return 200 idempotently");
const jsonNonExistent = await resDeleteNonExistent.json();
assert.strictEqual(jsonNonExistent.status, "deleted");
assert.strictEqual(jsonNonExistent.slug, "non-existent-post");
} finally {
await new Promise((resolve) => server.close(resolve));
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(tmpPosts, { recursive: true, force: true });
}
});
test("Ingestion API: triggerEleventyBuild builds site and handles concurrency", async () => {
assert.strictEqual(typeof triggerEleventyBuild, "function");
// Trigger two concurrent calls to assert queuing does not crash or throw
const [b1, b2] = await Promise.all([triggerEleventyBuild(), triggerEleventyBuild()]);
assert.strictEqual(b1, undefined);
assert.strictEqual(b2, undefined);
});
test/linked-articles.test.js
-153
View File
@@ -1,153 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { resolveLinkedArticles, validateLinkedArticles } from "../src/_utils/linked-articles.js";
import { filters } from "../src/_filters/index.js";
import configureEleventy from "../eleventy.config.js";
test("Linked articles: accepts an article's list when every name identifies another post", () => {
assert.doesNotThrow(() => {
validateLinkedArticles([
{
inputPath: "src/posts/2026-10-06-terminal-preview-demo.md",
data: {
title: "Terminal Preview Demo",
linkedArticles: ["Markdown Preview Demo"]
}
},
{
inputPath: "src/posts/2026-10-05-markdown-preview-demo.md",
data: { title: "Markdown Preview Demo" }
}
]);
});
});
test("Linked articles: rejects a non-list frontmatter value", () => {
assert.throws(
() => {
validateLinkedArticles([
{
inputPath: "src/posts/2026-10-06-terminal-preview-demo.md",
data: {
title: "Terminal Preview Demo",
linkedArticles: "Markdown Preview Demo"
}
},
{
inputPath: "src/posts/2026-10-05-markdown-preview-demo.md",
data: { title: "Markdown Preview Demo" }
}
]);
},
/must define 'linkedArticles' as a YAML list/
);
});
test("Linked articles: rejects empty and unknown article names", () => {
const posts = [
{
inputPath: "src/posts/2026-10-06-terminal-preview-demo.md",
data: { title: "Terminal Preview Demo", linkedArticles: [""] }
},
{
inputPath: "src/posts/2026-10-05-markdown-preview-demo.md",
data: { title: "Markdown Preview Demo" }
}
];
assert.throws(() => validateLinkedArticles(posts), /non-empty article titles/);
posts[0].data.linkedArticles = ["Missing Dispatch"];
assert.throws(() => validateLinkedArticles(posts), /links to unknown article 'Missing Dispatch'/);
});
test("Linked articles: rejects self-references and duplicate navigation targets", () => {
const posts = [
{
inputPath: "src/posts/2026-10-06-terminal-preview-demo.md",
data: {
title: "Terminal Preview Demo",
linkedArticles: ["Terminal Preview Demo"]
}
},
{
inputPath: "src/posts/2026-10-05-markdown-preview-demo.md",
data: { title: "Markdown Preview Demo" }
}
];
assert.throws(() => validateLinkedArticles(posts), /cannot link to itself/);
posts[0].data.linkedArticles = ["Markdown Preview Demo", "Markdown Preview Demo"];
assert.throws(() => validateLinkedArticles(posts), /cannot contain duplicate article titles/);
});
test("Linked articles: the Eleventy posts collection rejects invalid frontmatter", () => {
const collections = new Map();
configureEleventy({
setUseGitIgnore() {},
addPassthroughCopy() {},
addPlugin() {},
setLibrary() {},
addFilter() {},
addCollection(name, callback) {
collections.set(name, callback);
},
setServerOptions() {}
});
assert.throws(
() => {
collections.get("posts")({
getFilteredByGlob() {
return [
{
inputPath: "src/posts/2026-10-06-terminal-preview-demo.md",
data: {
title: "Terminal Preview Demo",
linkedArticles: ["Missing Dispatch"]
}
}
];
}
});
},
/links to unknown article 'Missing Dispatch'/
);
});
test("Linked articles: resolves named posts in the frontmatter order for navigation", () => {
const posts = [
{
url: "/dispatches/terminal-preview-demo/",
data: { title: "Terminal Preview Demo" }
},
{
url: "/dispatches/markdown-preview-demo/",
data: { title: "Markdown Preview Demo" }
}
];
assert.deepEqual(
resolveLinkedArticles(posts, ["Markdown Preview Demo", "Terminal Preview Demo"]),
[posts[1], posts[0]]
);
});
test("Linked articles: exposes navigation resolution to Nunjucks", () => {
assert.strictEqual(filters.resolveLinkedArticles, resolveLinkedArticles);
});
test("Linked articles: post layout renders Other Articles at the top of dispatch telemetry", () => {
const postLayout = fs.readFileSync(
path.resolve("src/_includes/layouts/post.njk"),
"utf-8"
);
assert.match(
postLayout,
/{% set linkedPosts = collections\.posts \| resolveLinkedArticles\(linkedArticles\) %}[\s\S]*?<div[^>]+class="sidebar-heading">OTHER ARTICLES<\/div>[\s\S]*?<nav[^>]+aria-label="Other Articles">[\s\S]*?href="{{ linkedPost\.url }}"/
);
});
test/local-post-fixtures.test.js
-10
View File
@@ -1,10 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const config = fs.readFileSync(path.resolve("eleventy.config.js"), "utf-8");
test("Eleventy config: builds local ignored post fixtures", () => {
assert.match(config, /setUseGitIgnore\(false\)/);
});
test/not-found.test.js
-43
View File
@@ -1,43 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { execFileSync } from "node:child_process";
import { createServer } from "../server.js";
const siteDir = path.resolve("_site");
test("unknown routes render the themed 404 page with a real 404 status", async () => {
execFileSync("npm", ["run", "build"], {
stdio: "pipe",
env: { ...process.env, SITE_DOMAIN: process.env.SITE_DOMAIN || "riverrooks.dev" }
});
const html = fs.readFileSync(path.join(siteDir, "404.html"), "utf8");
assert.match(html, /<title>Page not found/);
assert.match(html, /<h1[^>]*>[^<]*404/);
assert.match(html, /href="\/"/);
assert.match(html, /href="\/dispatches\/"/);
assert.match(html, /href="\/assets\/css\/main\.css/);
const css = fs.readFileSync(path.join(siteDir, "assets/css/main.css"), "utf8");
assert.match(css, /components\/not-found\.css/);
const pageCss = fs.readFileSync(path.join(siteDir, "assets/css/components/not-found.css"), "utf8");
assert.doesNotMatch(pageCss, /(?:backdrop-filter|box-shadow|text-shadow|linear-gradient|radial-gradient)\s*:/);
const server = createServer(siteDir, path.resolve("src/posts"), path.resolve("src/assets/images/posts"));
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
try {
const origin = `http://127.0.0.1:${server.address().port}`;
for (const route of ["/missing-page/", "/assets/missing.css"]) {
const response = await fetch(`${origin}${route}`);
assert.equal(response.status, 404);
assert.match(response.headers.get("content-type"), /text\/html/);
assert.match(await response.text(), /Page not found/);
}
const home = await fetch(origin);
assert.equal(home.status, 200);
} finally {
await new Promise((resolve) => server.close(resolve));
}
});
test/obsidian-plugin.test.js
-162
View File
@@ -1,162 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const pluginPath = path.resolve("/home/venus/Documents/Notes/.obsidian/plugins/blog-publisher/main.js");
// Pure helper function to be tested and exported/used by plugin
export function insertOrUpdateFrontmatterProperty(content, key, value) {
if (typeof content !== "string") return "";
const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---/;
const match = content.match(fmRegex);
if (match) {
let fmBlock = match[1];
const keyRegex = new RegExp(`^${key}:.*$`, "m");
if (value === null || value === undefined) {
// Remove property if value is null
fmBlock = fmBlock.replace(new RegExp(`^${key}:.*\\r?\\n?`, "m"), "");
} else if (keyRegex.test(fmBlock)) {
// Replace existing property
fmBlock = fmBlock.replace(keyRegex, `${key}: "${value}"`);
} else {
// Append property to frontmatter
fmBlock = `${fmBlock}\n${key}: "${value}"`;
}
return content.replace(fmRegex, `---\n${fmBlock.trim()}\n---`);
} else if (value) {
return `---\n${key}: "${value}"\n---\n\n${content}`;
}
return content;
}
export function computePublicUrl(serverUrl, postPath) {
const base = (serverUrl || "").replace(/\/+$/, "");
const p = (postPath || "").startsWith("/") ? postPath : `/${postPath || ""}`;
return `${base}${p}`;
}
test("Obsidian Plugin: computePublicUrl normalizes slashes correctly", () => {
assert.equal(
computePublicUrl("https://riverrooks.dev", "/posts/test-note/"),
"https://riverrooks.dev/posts/test-note/"
);
assert.equal(
computePublicUrl("https://riverrooks.dev/", "/posts/test-note/"),
"https://riverrooks.dev/posts/test-note/"
);
assert.equal(
computePublicUrl("https://riverrooks.dev///", "posts/test-note/"),
"https://riverrooks.dev/posts/test-note/"
);
assert.equal(
computePublicUrl("http://localhost:8080", "/posts/test-note/"),
"http://localhost:8080/posts/test-note/"
);
});
test("Obsidian Plugin: insertOrUpdateFrontmatterProperty adds public-url when missing", () => {
const original = `---
title: "Sample Note"
date: 2026-09-23
publish: true
---
# Content here`;
const updated = insertOrUpdateFrontmatterProperty(
original,
"public-url",
"https://riverrooks.dev/posts/sample-note/"
);
assert.match(
updated,
/public-url:\s*"https:\/\/riverrooks\.dev\/posts\/sample-note\/"/,
"Must insert public-url into frontmatter"
);
assert.match(updated, /title:\s*"Sample Note"/, "Preserves title");
assert.match(updated, /publish:\s*true/, "Preserves publish flag");
assert.match(updated, /# Content here/, "Preserves body content");
});
test("Obsidian Plugin: insertOrUpdateFrontmatterProperty updates existing public-url", () => {
const original = `---
title: "Updated Note"
date: 2026-09-23
public-url: "https://old.domain/posts/sample-note/"
---
Body`;
const updated = insertOrUpdateFrontmatterProperty(
original,
"public-url",
"https://riverrooks.dev/posts/updated-note/"
);
assert.match(
updated,
/public-url:\s*"https:\/\/riverrooks\.dev\/posts\/updated-note\/"/,
"Must update public-url to new URL"
);
assert.doesNotMatch(
updated,
/old\.domain/,
"Old URL must be replaced"
);
});
test("Obsidian Plugin: insertOrUpdateFrontmatterProperty removes public-url on unpublish", () => {
const original = `---
title: "Unpublished Note"
date: 2026-09-23
public-url: "https://riverrooks.dev/posts/sample-note/"
---
Body`;
const updated = insertOrUpdateFrontmatterProperty(original, "public-url", null);
assert.doesNotMatch(updated, /public-url:/, "Must remove public-url when value is null");
assert.match(updated, /title:\s*"Unpublished Note"/, "Preserves other frontmatter");
});
test("Obsidian Plugin: Adversarial edge cases for frontmatter property insertion", () => {
// 1. Empty content
assert.equal(insertOrUpdateFrontmatterProperty("", "public-url", "https://url"), "---\npublic-url: \"https://url\"\n---\n\n");
// 2. Non-string inputs
assert.equal(insertOrUpdateFrontmatterProperty(null, "public-url", "https://url"), "");
assert.equal(insertOrUpdateFrontmatterProperty(undefined, "public-url", "https://url"), "");
// 3. Note without frontmatter
const plain = "# Just a header\nSome text.";
const result = insertOrUpdateFrontmatterProperty(plain, "public-url", "https://url");
assert.match(result, /^---\npublic-url:\s*"https:\/\/url"\n---/);
});
test("Obsidian Plugin: main.js in vault includes public-url insertion and recursion guard", () => {
assert.ok(fs.existsSync(pluginPath), `Plugin main.js must exist at ${pluginPath}`);
const pluginContent = fs.readFileSync(pluginPath, "utf-8");
// 1. Must handle public-url
assert.match(pluginContent, /public-url/i, "main.js must reference 'public-url'");
// 2. Must guard against infinite loops during frontmatter updates
assert.match(
pluginContent,
/isUpdatingFrontmatter/i,
"main.js must maintain a guard to prevent metadataCache recursion loops"
);
// 3. Must use processFrontMatter or frontmatter updater
assert.match(
pluginContent,
/processFrontMatter|updateFrontmatter/i,
"main.js must implement frontmatter updating logic"
);
});
test/post-sorting.test.js
-104
View File
@@ -1,104 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import { postComparator, isPostPinned, getPostTimestamp } from "../src/_utils/sort-posts.js";
test("Post Sorting: isPostPinned detection", () => {
assert.equal(isPostPinned({ data: { pinned: true } }), true);
assert.equal(isPostPinned({ data: { featured: true } }), true);
assert.equal(isPostPinned({ data: { pinned: false } }), false);
assert.equal(isPostPinned({ data: { featured: false } }), false);
assert.equal(isPostPinned({ data: { pinned: null } }), false);
assert.equal(isPostPinned({ data: {} }), false);
assert.equal(isPostPinned({}), false);
assert.equal(isPostPinned(null), false);
assert.equal(isPostPinned(undefined), false);
assert.equal(isPostPinned("invalid"), false);
});
test("Post Sorting: getPostTimestamp extraction and fallback", () => {
const d = new Date("2026-09-01T00:00:00Z");
assert.equal(getPostTimestamp({ date: d }), d.getTime());
assert.equal(getPostTimestamp({ data: { date: "2026-09-01" } }), new Date("2026-09-01").getTime());
assert.equal(getPostTimestamp({ data: { created: "2026-09-01" } }), new Date("2026-09-01").getTime());
assert.equal(getPostTimestamp({ date: "not-a-date" }), 0);
assert.equal(getPostTimestamp({}), 0);
assert.equal(getPostTimestamp(null), 0);
});
test("Post Sorting: standard chronological sort (unpinned posts)", () => {
const postNew = {
data: { title: "Newer Post" },
date: new Date("2026-09-10")
};
const postOld = {
data: { title: "Older Post" },
date: new Date("2026-08-01")
};
const sorted = [postOld, postNew].sort(postComparator);
assert.deepEqual(sorted.map((p) => p.data.title), ["Newer Post", "Older Post"]);
});
test("Post Sorting: pinned post forces top position over newer unpinned post", () => {
const newerUnpinned = {
data: { title: "Newer Unpinned", pinned: false },
date: new Date("2026-09-20")
};
const olderPinned = {
data: { title: "Older Pinned", pinned: true },
date: new Date("2026-07-01")
};
const sorted = [newerUnpinned, olderPinned].sort(postComparator);
assert.equal(sorted[0].data.title, "Older Pinned");
assert.equal(sorted[1].data.title, "Newer Unpinned");
});
test("Post Sorting: featured post forces top position over newer unpinned post", () => {
const newerRegular = {
data: { title: "Fresh Article" },
date: new Date("2026-09-22")
};
const olderFeatured = {
data: { title: "Featured Pillar", featured: true },
date: new Date("2026-06-15")
};
const sorted = [newerRegular, olderFeatured].sort(postComparator);
assert.equal(sorted[0].data.title, "Featured Pillar");
assert.equal(sorted[1].data.title, "Fresh Article");
});
test("Post Sorting: multiple pinned posts sort among themselves chronologically", () => {
const olderPinned = {
data: { title: "Older Pinned", pinned: true },
date: new Date("2026-05-01")
};
const newerPinned = {
data: { title: "Newer Pinned", featured: true },
date: new Date("2026-08-15")
};
const freshUnpinned = {
data: { title: "Fresh Regular" },
date: new Date("2026-09-01")
};
const list = [olderPinned, freshUnpinned, newerPinned];
const sorted = list.sort(postComparator);
assert.deepEqual(
sorted.map((p) => p.data.title),
["Newer Pinned", "Older Pinned", "Fresh Regular"]
);
});
test("Post Sorting: adversarial robustness against missing data or equal dates", () => {
const postNoData = { date: new Date("2026-09-01") };
const postMalformedDate = { data: { title: "Malformed", date: "invalid-date" } };
const postIdenticalDate1 = { data: { title: "Post A" }, date: new Date("2026-09-01") };
const postIdenticalDate2 = { data: { title: "Post B" }, date: new Date("2026-09-01") };
assert.doesNotThrow(() => {
[postNoData, postMalformedDate, postIdenticalDate1, postIdenticalDate2].sort(postComparator);
});
});
test/post-terminal-preview-layout.test.js
-10
View File
@@ -1,10 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const postLayout = fs.readFileSync(path.resolve("src/_includes/layouts/post.njk"), "utf-8");
test("Post layout: omits the leading terminal preview from the public article body", () => {
assert.match(postLayout, /content\s*\|\s*removeTerminalPreview\s*\|\s*safe/);
});
test/server.test.js
-87
View File
@@ -1,87 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import http from "node:http";
import path from "node:path";
import { execSync } from "node:child_process";
import { createServer } from "../server.js";
const TEST_PORT = 8999;
const BASE_URL = `http://127.0.0.1:${TEST_PORT}`;
// Helper to perform HTTP GET requests
function get(urlPath) {
return new Promise((resolve, reject) => {
http.get(`${BASE_URL}${urlPath}`, (res) => {
let data = "";
res.on("data", (chunk) => (data += chunk));
res.on("end", () => {
resolve({
statusCode: res.statusCode,
headers: res.headers,
body: data
});
});
}).on("error", reject);
});
}
test("Node Static Server: lifecycle, routing, and adversarial security tests", async (t) => {
// Ensure _site exists before running server tests
if (!fs.existsSync(path.resolve(process.cwd(), "_site/index.html"))) {
execSync("npm run build", {
stdio: "pipe",
env: { ...process.env, SITE_DOMAIN: "riverrooks.dev" }
});
}
const server = createServer();
await new Promise((resolve) => server.listen(TEST_PORT, "127.0.0.1", resolve));
t.after(() => {
return new Promise((resolve) => server.close(resolve));
});
await t.test("serves root index.html with 200 OK and text/html", async () => {
const res = await get("/");
assert.equal(res.statusCode, 200);
assert.match(res.headers["content-type"], /text\/html/);
assert.match(res.body, /<!DOCTYPE html>/i);
// Verify security headers
assert.equal(res.headers["x-content-type-options"], "nosniff");
assert.equal(res.headers["x-frame-options"], "DENY");
});
await t.test("serves clean directory URL (/dispatches/)", async () => {
const res = await get("/dispatches/");
assert.equal(res.statusCode, 200);
assert.match(res.headers["content-type"], /text\/html/);
});
await t.test("serves static assets with appropriate Content-Type", async () => {
const res = await get("/assets/css/main.css");
assert.equal(res.statusCode, 200);
assert.match(res.headers["content-type"], /text\/css/);
});
await t.test("responds with 200 OK JSON on /healthz", async () => {
const res = await get("/healthz");
assert.equal(res.statusCode, 200);
assert.match(res.headers["content-type"], /application\/json/);
const body = JSON.parse(res.body);
assert.equal(body.status, "ok");
});
await t.test("returns 404 Not Found for non-existent routes", async () => {
const res = await get("/non-existent-file-xyz.html");
assert.equal(res.statusCode, 404);
});
await t.test("adversarial: blocks path traversal attempts", async () => {
const res = await get("/../../../../etc/passwd");
// Must either return 403 Forbidden or 404 Not Found, never 200
assert.notEqual(res.statusCode, 200);
assert.ok(res.statusCode === 403 || res.statusCode === 404);
assert.doesNotMatch(res.body, /root:x:/);
});
});
test/site-config.test.js
-64
View File
@@ -1,64 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import { execSync } from "node:child_process";
test("Site Config: throws explicit error when SITE_DOMAIN is unset", () => {
// Run isolated Node process with empty environment to verify error throw
const cmd = `node -e '
process.env.SITE_DOMAIN = "";
delete process.env.SITE_DOMAIN;
// mock empty cwd without .env
process.chdir("/tmp");
import("${process.cwd()}/src/_data/site.js")
.then(() => process.exit(0))
.catch(err => {
if (err.message.includes("FATAL CONFIGURATION ERROR: SITE_DOMAIN")) {
process.exit(42);
}
process.exit(1);
});
'`;
try {
execSync(cmd, { stdio: "pipe" });
assert.fail("Should have thrown error when SITE_DOMAIN is missing");
} catch (err) {
assert.equal(err.status, 42, "Process exited with status 42 (expected error caught)");
}
});
test("Site Config: correctly parses SITE_DOMAIN and derives service subdomains", async () => {
process.env.SITE_DOMAIN = "testcluster.internal";
delete process.env.SITE_URL;
// Import site configuration dynamically
const { default: site } = await import(`../src/_data/site.js?t=${Date.now()}`);
assert.equal(site.domain, "testcluster.internal");
assert.equal(site.url, "https://testcluster.internal");
// Verify dynamic subdomains
const gitService = site.services.find((s) => s.name === "Gitea");
assert.ok(gitService, "Gitea service exists");
assert.equal(gitService.url, "https://git.riverrooks.dev/venus");
assert.equal(gitService.tag, "git.testcluster.internal:443");
// Verify navigation links
const navHome = site.nav.find((n) => n.label === "Home");
assert.ok(navHome, "Nav Home link exists");
assert.equal(navHome.url, "/");
const navCode = site.nav.find((n) => n.label === "Code");
assert.ok(navCode, "Nav Code link exists");
assert.equal(navCode.url, "https://git.riverrooks.dev/venus");
});
test("Site Config: respects explicit SITE_URL override", async () => {
process.env.SITE_DOMAIN = "riverrooks.dev";
process.env.SITE_URL = "http://localhost:8080";
const { default: site } = await import(`../src/_data/site.js?t=${Date.now()}`);
assert.equal(site.domain, "riverrooks.dev");
assert.equal(site.url, "http://localhost:8080");
});
test/standards-verification.test.js
-92
View File
@@ -1,92 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
const skillDir = path.resolve(".agents/skills/standards-verification");
const skillPath = path.join(skillDir, "SKILL.md");
const standardsDocPath = path.resolve(".agents/standards.md");
const skillStandardsRefPath = path.join(skillDir, "references/standards.md");
test("Standards Verification Skill: Directory, SKILL.md, and standards document exist", () => {
assert.ok(fs.existsSync(skillDir), ".agents/skills/standards-verification directory must exist");
assert.ok(fs.existsSync(skillPath), "SKILL.md must exist in standards-verification skill");
assert.ok(fs.existsSync(standardsDocPath), "Dedicated standards document .agents/standards.md must exist");
assert.ok(fs.existsSync(skillStandardsRefPath), "Skill references/standards.md must exist");
});
test("Standards Verification Skill: SKILL.md contains correct metadata and execution directives", () => {
const content = fs.readFileSync(skillPath, "utf-8");
// 1. YAML frontmatter name and description
assert.match(content, /^---\s*\nname:\s*standards-verification/m, "Must declare name: standards-verification");
assert.match(content, /description:\s*>-?[\s\S]*?---/, "Must define description in frontmatter");
// 2. Invocation conditions: called sparingly, major feature, user request, or debugging
assert.match(content, /sparingly/i, "Must specify calling sparingly and only when needed");
assert.match(content, /major\s+function|major\s+feature/i, "Must mention use case: major function/feature implemented");
assert.match(content, /user(?:\s+\w+)?\s+asks/i, "Must mention use case: user explicitly requests verification");
assert.match(content, /debug(?:ging)?/i, "Must mention use case: debugging code issues");
// 3. Targeted inspection via git status / git diff (not whole codebase unless necessary)
assert.match(content, /git\s+status/i, "Must specify using git status to identify changes");
assert.match(content, /git\s+diff/i, "Must specify using git diff to inspect targeted changes");
assert.match(content, /not\s+(?:the\s+)?whole\s+codebase/i, "Must specify NOT inspecting whole codebase unless necessary");
// 4. Debugging guidance: explain why standards violations cause errors
assert.match(content, /(?:suggest|explain)[*\s`_]+why/i, "Must instruct suggesting why standards issues cause errors");
// 5. External standards document reference
assert.match(content, /standards\.md/i, "Must refer to standards.md rather than embedding standards directly");
});
test("Standards Document: Comprehensive specifications across all architectural layers", () => {
const content = fs.readFileSync(standardsDocPath, "utf-8");
// 1. Design & CSS Anti-Patterns
assert.match(content, /backdrop-filter/i, "Must document prohibition on backdrop-filter");
assert.match(content, /box-shadow/i, "Must document prohibition on box-shadow");
assert.match(content, /gradient/i, "Must document prohibition on gradients");
assert.match(content, /border-radius/i, "Must document border-radius constraints (0px to 4px)");
assert.match(content, /instant/i, "Must document instant binary transitions");
// 2. Templating & Eleventy
assert.match(content, /isPostPublic/i, "Must document isPostPublic collection filtering");
assert.match(content, /hidden/i, "Must document hidden post behavior and noindex meta tag");
// 3. Frontmatter & Content Contract
assert.match(content, /title/i, "Must document title requirement");
assert.match(content, /date|created/i, "Must document date requirement");
assert.match(content, /tags/i, "Must document tags requirement");
assert.match(content, /excerpt/i, "Must document excerpt requirement");
// 4. Server & Security Invariants
assert.match(content, /path\s+traversal/i, "Must document path traversal defense");
assert.match(content, /healthz/i, "Must document healthcheck endpoint");
assert.match(content, /X-Content-Type-Options/i, "Must document security headers");
// 5. Strict TDD & Verification Invariants
assert.match(content, /before\s+(?:writing\s+or\s+)?modifying/i, "Must mandate tests before modifying functional code");
assert.match(content, /adversarial/i, "Must mandate adversarial testing");
assert.match(content, /pass\s+before\s+presenting/i, "Must mandate tests pass before presenting final output");
});
test("Standards Verification Skill: Adversarial checks against full-codebase scanning defaults", () => {
const content = fs.readFileSync(skillPath, "utf-8");
// Adversarial: ensure no instruction tells the agent to indiscriminately scan everything by default
assert.doesNotMatch(
content,
/always\s+scan\s+(?:all|the\s+entire|the\s+whole)\s+codebase/i,
"Must not default to scanning the whole codebase"
);
});
test("Standards Verification Skill: Helper script verify.js exists and executes safely", () => {
const scriptPath = path.join(skillDir, "scripts/verify.js");
assert.ok(fs.existsSync(scriptPath), "scripts/verify.js must exist");
const content = fs.readFileSync(scriptPath, "utf-8");
assert.match(content, /git\s+status/i, "Script must inspect git status");
});
test/terminal-preview-boundary.test.js
-15
View File
@@ -1,15 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import { extractTerminalPreview, removeTerminalPreview } from "../src/_filters/index.js";
test("Terminal previews: stop before the first subsequent Markdown heading at any level", () => {
const renderedPost = `
<h1 id="terminal-preview">Terminal preview</h1>
<p>Plain Markdown preview text is supported.</p>
<h2 id="findings">Findings</h2>
<p>The article begins here.</p>
`;
assert.match(extractTerminalPreview(renderedPost), /Plain Markdown preview text/);
assert.match(removeTerminalPreview(renderedPost), /^\n <h2 id="findings">/);
});
test/terminal-preview.test.js
-37
View File
@@ -1,37 +0,0 @@
import test from "node:test";
import assert from "node:assert/strict";
import {
extractTerminalPreview,
removeTerminalPreview
} from "../src/_filters/index.js";
test("Terminal previews: extracts rendered Markdown between the leading preview and article headings", () => {
const renderedPost = `
<h1 id="terminal-preview">Terminal preview</h1>
<p>Use the following command:</p>
<pre class="language-bash"><code class="language-bash">cat /dispatches/example | head -n 5</code></pre>
<h1 id="investigation">Investigation</h1>
<p>The public article starts here.</p>
`;
assert.equal(
extractTerminalPreview(renderedPost),
`\n <p>Use the following command:</p>\n <pre class="language-bash"><code class="language-bash">cat /dispatches/example | head -n 5</code></pre>\n `
);
assert.equal(
removeTerminalPreview(renderedPost),
`\n <h1 id="investigation">Investigation</h1>\n <p>The public article starts here.</p>\n `
);
});
test("Terminal previews: ignores missing, misplaced, and malformed preview headings", () => {
const regularPost = "<h1 id=\"article\">Article</h1><p>Visible text.</p>";
const misplacedPreview = "<h1 id=\"article\">Article</h1><h1 id=\"terminal-preview\">Terminal preview</h1><p>Do not extract.</p>";
assert.equal(extractTerminalPreview(regularPost), "");
assert.equal(removeTerminalPreview(regularPost), regularPost);
assert.equal(extractTerminalPreview(misplacedPreview), "");
assert.equal(removeTerminalPreview(misplacedPreview), misplacedPreview);
assert.equal(extractTerminalPreview(null), "");
assert.equal(removeTerminalPreview(null), "");
});