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)

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/*).
No Unsolicited Modifications:
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
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

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.
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.
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

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).
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.
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

Frontmatter Schema:

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)

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

Native Runtime:
- server.js uses native Node standard library (node:http, node:fs, node:path) with zero external runtime dependencies.
Security Headers on All Responses:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- Referrer-Policy: strict-origin-when-cross-origin
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.
Healthcheck Telemetry:
- /healthz and /health must respond with HTTP 200 JSON { status: "ok", uptime: <seconds> }.

7. Defensive Programming & Error Prevention

Input Guarding:
- Never assume incoming arguments have expected shape. Always guard against null, undefined, non-objects, and primitive inputs (e.g., item.data ?? item).
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).

6.8 KiB Raw Blame History