Noticiencias Frontend

Parte del ecosistema Tooltician — periodismo científico, reproducible y open-source.

Frontend repo for noticiencias.com.

This repository is a static Astro 6 site with MD/MDX content under src/content/posts, a custom Astrowind-derived shell, and a small amount of page-scoped browser behavior. It is the presentation layer of the Noticiencias system; ingestion, scoring, editorial automation, and publication orchestration live in the sibling backend repo ../noticiencias_news_collector.

Current State

• Rendering model: server-first Astro with ClientRouter view transitions enabled in src/layouts/template/Layout.astro.
• Content contract: the only authoritative post schema is src/content.config.ts.
• Site/blog configuration: canonical site metadata, robots defaults, and route pathnames live in src/config.yaml.
• Metadata emission: pages pass metadata through layouts into src/components/template/common/Metadata.astro.
• URL and taxonomy helpers: src/utils/permalinks.ts and src/utils/blog.ts.
• Search: build-time JSON at src/pages/search.json.js plus a browser-only Lunr UI on src/pages/buscar.astro.
• Deployment: GitHub Pages via .github/workflows/deploy.yml.

Key Directories

• src/content/posts/: published articles.
• src/pages/: route entrypoints and static path generation.
• src/layouts/: page shells and metadata plumbing.
• src/components/ds/: Noticiencias design-system primitives.
• src/components/template/: Astrowind-derived shell, blog widgets, and shared template pieces.
• src/components/common/: site-specific reusable fragments that do not fit ds or template.
• src/utils/: mostly pure data, permalink, search, and image helpers.
• src/integration/: custom integration that exposes astrowind:config from src/config.yaml.
• tests/: Vitest coverage for search helpers, slug uniqueness, site integrity, and compliance checks.

Development

npm ci
npm run lint
npm run validate:content
npm run build
npm run test:dist
npm run test:audit

Useful local commands:

• npm run dev
• npm run publish:image-derivatives
• npm run lint
• npm run validate:content
• npm run build
• npm run test:dist
• npm run test:audit
• npm run test:deploy -- <deployed-url>

Image Derivatives

• Post hero images now use a generated manifest at data/image-derivatives-manifest.json.
• npm run publish:image-derivatives scans local post raster images, computes deterministic derivative keys, updates the manifest, and uploads missing AVIF variants when the R2 env vars are present.
• Required Cloudflare env vars for upload mode: R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME, R2_ENDPOINT, and R2_PUBLIC_BASE_URL.
• Without those env vars, the script still refreshes the manifest metadata locally and the site falls back to Astro image optimization during build.
• The GitHub Pages deploy workflow auto-enables IMAGE_DERIVATIVES_REQUIRE_URL=1 and IMAGE_DERIVATIVES_STRICT=1 once those R2 env vars are configured in CI. At that point, deploy builds stop accepting Astro fallback for post images and require published CDN derivative URLs instead.

Governance Docs

• AGENTS.md: binding review and change law for this repo.
• docs/SOURCE_OF_TRUTH.md: governance stack, authority model, and repo boundary with the backend.
• docs/ARCHITECTURE.md: actual module boundaries, data flow, and extension rules.
• docs/tagging.md: cross-repo tagging contract.
• docs/audits/2026-04-source-of-truth-audit.md: documentation audit for this pass.
• docs/backlog/source-of-truth-backlog.md: prioritized follow-up backlog.

Back-End System

Content is collected, enriched, and published by the companion back-end repo noticiencias_news_collector.

Key references for understanding the full system:

• ../noticiencias_news_collector/docs/PRODUCT_FLOW.md: end-to-end product flow from RSS article to live page.
• ../noticiencias_news_collector/docs/PIPELINE_CONTRACTS.md: cross-repo contract shapes and failure semantics.
• ../noticiencias_news_collector/docs/RUNBOOK_LOCAL_DEV.md: local bootstrap guide for both repos.

Notes

• This repo does not currently use React islands or a separate client framework.
• Historical migration material under docs/migration/ and docs/logs/MIGRATION_LOG.md is useful context, but it is not the operational source of truth for the current site.

---

Built and maintained by Carlos Ortega — automation, data systems, and web technical hygiene consulting. Portfolio and services: tooltician.com.

Part of the Tooltician ecosystem — periodismo científico, reproducible y open-source.