Imported from Niall-Young/Blogme-framework (AGENTS.md). Install upstream with npx skills add Niall-Young/Blogme-framework. Copyright stays with the author.

Agent Guide

This file is for coding agents working in this repository. Follow it before changing files.

Project Overview

Blogme is an Astro 5 static blog framework for Markdown notes on Cloudflare Pages. It renders local sample articles from src/content/articles and can optionally sync real articles from an external GitHub Markdown repository before build.

Important paths:

• src/site.config.ts: site name, description, navigation, author links, optional contact images, and share copy.
• src/pages/index.astro: home article search, list, and pagination.
• src/pages/blog/[slug].astro: generated article detail pages.
• src/layouts/BaseLayout.astro: shared document shell, metadata, header, footer, and global CSS import.
• src/components: shared Astro components.
• src/components/ui: local UI primitives and icon wrapper.
• src/styles/global.css: design tokens, layout, component styles, responsive rules, and markdown styles.
• src/content/config.ts: Astro content collection schema.
• src/lib/articles.ts: article sorting, fallback sample filtering, dates, tags, related-article helpers.
• src/lib/paths.ts: base-path-safe internal URL helper.
• scripts/sync-content.mjs: external Markdown sync script.
• docs/article-template.md: article frontmatter template.

Commands

Use npm, not yarn or pnpm, because this repo has package-lock.json.

npm install
npm run dev
npm run build
npm run build:cloudflare
npm run preview
npm run deploy:cloudflare
npm run sync:content

npm run build runs astro check and then astro build. Use it as the default verification command after code, style, route, content schema, or config changes.

Content Sync

npm run sync:content only syncs an external repository when CONTENT_REPO_URL is set. Without it, the command exits successfully and keeps local sample articles.

Supported environment variables:

• CONTENT_REPO_URL: GitHub Markdown repository URL.
• CONTENT_REPO_REF: optional branch, tag, or commit.
• CONTENT_SOURCE_DIR: optional subdirectory to sync.
• CONTENT_INCLUDE_README=true: include README files.
• CONTENT_SOURCE_ATTRIBUTION: optional Markdown attribution inserted into synced articles.
• CONTENT_REPO_TOKEN: optional Cloudflare secret for private GitHub repositories.

Generated remote-*.md files and copied external assets are ignored by Git. Do not edit .content-cache manually.

UI Rules

Read design.md before making visual changes.

• Reuse src/components/ui/Button.astro, Badge.astro, and MingIcon.astro before adding new primitives.
• Add icons through the MingIcon iconMap; avoid inline one-off SVGs in page files.
• Keep the warm editorial token system in src/styles/global.css.
• Keep article index rows stable: the search script depends on article card data attributes.
• Preserve mobile behavior for header, article list rows, article hero, and footer content.
• Do not introduce React, Vue, Svelte, Tailwind, or a client-side router unless explicitly requested or clearly necessary.

Routing And URLs

Always use pathFor() for internal links and public asset URLs in Astro components. Cloudflare Pages serves this framework from the site root, so do not add project-page base-path logic.

Verification Checklist

For most changes:

npm run build

For UI changes:

• Run the dev server.
• Check desktop and mobile widths.
• Verify home search and pagination.
• Open at least one article page.

For content sync changes:

• Run npm run sync:content.
• Confirm generated src/content/articles/remote-*.md files build successfully if a repository URL is configured.
• Run npm run build.