venus
d8fb8a3699
- Add project foundation README.md and root AGENTS.md for pair programming - Configure .agents/ rules and skills for Eleventy tiling and Obsidian publishing - Decompose monolithic styles into modular tokens, reset, layout, and component CSS - Implement Nunjucks layout inheritance (base.njk, post.njk, page.njk) and reusable partials - Configure Eleventy 3 with markdown-it-anchor, syntax highlighting, and dynamic collections - Migrate sample prototypes into dynamic dispatches lander, gateway, and Markdown posts - Add multi-stage Dockerfile and clean-URL nginx.conf for production serving
3.0 KiB
3.0 KiB
Technical Blog System Rules & Architecture Directives
1. Pedagogical Explanations (Interactive Learning)
- Explain the Code: Whenever creating or refactoring code (Eleventy configuration, Nunjucks templates, CSS modules, build scripts), provide a clear, educational breakdown.
- 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.
- No Magic: Avoid opaque or overly clever abstractions; prioritize readable, idiomatic code with commentary explaining tricky points.
2. CSS Architecture & Isolation
- Zero Monolithic Inlines: Do not inject raw
<style>blocks into HTML templates. - 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.
- Put global tokens in
- 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)
- Canvas:
- Hard Aesthetic Constraints:
- No glassmorphism (
backdrop-filter). - No box-shadows or glows.
- No linear/radial gradients.
- Border radius strictly bounded between
0pxand4px. - Transition durations set to
noneor0sfor instant snap responses on hover.
- No glassmorphism (
3. Templating Guidelines (Eleventy + Nunjucks)
- 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).
- Root template:
- 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.
- Isolated partials in
4. Obsidian Content Pipeline
- Frontmatter Specification: Every post ingested from Obsidian must adhere to:
title: "Article Title" date: YYYY-MM-DD tags: ["#tag1", "#tag2"] excerpt: "Single paragraph summary" readingTime: "X MIN READ" draft: false - 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.
- Wikilinks