125 lines
6.8 KiB
Markdown
125 lines
6.8 KiB
Markdown
# 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$ ``.
|
|
- 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`).
|