From 6f39b7f929e2f35d873722419107a3b1709a9ad2 Mon Sep 17 00:00:00 2001 From: John Smith Date: Mon, 25 May 2026 00:47:53 +0100 Subject: [PATCH] docs: add blog agent workflow --- .github/copilot-instructions.md | 59 -------------- AGENTS.md | 139 ++++++++++++++++++++++++++++++++ README.md | 56 +++++++++++++ 3 files changed, 195 insertions(+), 59 deletions(-) delete mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index ccc1d2e..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,59 +0,0 @@ -# GitHub Copilot Instructions - -## Project Overview -This is a Jekyll-based static blog for solrevdev.com using the Hyde theme with custom modifications. - -## Key Development Guidelines - -### Blog Posts -- Located in `_posts/` directory -- Use Jekyll front matter with these fields: - - `layout: post` - - `title: [Post Title]` - - `description: [SEO description]` - - `summary: [Brief summary]` - - `cover_image: [/images/filename.ext]` (optional) - - `tags: [array of tags]` - -### Cover Images -- Store in `/images/` directory -- Use `cover_image: /images/filename.ext` in front matter -- Supported formats: SVG (preferred), PNG, JPG - all handled gracefully -- Size handling: CSS automatically scales images responsively -- Recommended dimensions: 800x400px aspect ratio -- Keep file size under 50KB for performance -- Optional field - posts without cover images work perfectly - -### Local Development Image Issues -**Important**: During local development, images may not display properly due to URL resolution: - -**Solutions**: -1. **Use Jekyll server**: `bundle exec jekyll serve --host 127.0.0.1 --port 4000` -2. **Use localhost domain**: `http://localhost:4000` or `http://127.0.0.1:4000` -3. **Relative paths work**: with file:// protocol for testing - -**Don't use**: -- Absolute paths (`/images/...`) with file:// protocol - will fail -- localhost URLs without running Jekyll server - -### Styling -- Custom styles in `public/css/custom.scss` -- Uses SCSS with Jekyll compilation -- Responsive breakpoints: 768px (tablet), 480px (mobile) -- Cover images have hover effects and responsive sizing - -### File Structure -``` -├── _posts/ # Blog posts -├── _layouts/ # Jekyll layouts -├── _includes/ # Jekyll includes -├── public/css/ # SCSS stylesheets -├── images/ # Blog post images -├── claude.md # Claude development notes -└── .github/ # GitHub configuration -``` - -### Testing -- Test responsive design at 375px (mobile), 768px (tablet), 1200px+ (desktop) -- Cover images scale automatically across all device sizes -- Posts without cover images display normally \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..df76c9d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,139 @@ +# AGENTS.md + +Repository-specific guidance for AI agents working on this Jekyll blog. + +## Project Overview + +This is the source for `solrevdev.com`, a Jekyll-based static blog using the +Hyde theme with custom styling. + +## Blog Posts + +Blog posts live in `_posts/` and use standard Jekyll front matter. New posts +should include: + +```yaml +--- +published: false +layout: post +title: Post Title +description: One concise SEO description. +summary: One concise home-page teaser. +cover_image: /images/post-cover.svg +tags: +- dotnet +- csharp +--- +``` + +Keep `published: false` while drafting unless the user explicitly asks to +publish the article. + +## Drafting Workflow + +- Before finalizing a draft, ask the user what publication date they want. +- If the post is not ready to publish, keep it in `_posts/` with + `published: false` or use `_drafts/` if the user asks for a true Jekyll draft. +- When publishing, rename the file to `_posts/YYYY-MM-DD-slug.md` and make sure + any `date:` front matter, if present, matches that filename date. +- Do not silently publish an article by removing `published: false`. +- If the user asks for a PR, keep the PR focused on the article and its related + assets unless they explicitly ask for wider site changes. + +## Writing Style + +- Match the tone of recent posts: practical, first-person, direct, and focused + on what was built, why it exists, how it works, and what comes next. +- Prefer concrete implementation details over generic marketing copy. +- Use the existing section rhythm when it fits the topic, for example: + `Overview`, `The Problem`, `What I Built`, `Implementation Highlights`, + `Testing Strategy`, and `What's Next`. +- Keep code examples runnable or clearly illustrative. +- New posts should normally end with the established sign-off: + +```markdown +Success! 🎉 +``` + +## Cover Images + +- New technical posts should normally have a cover image. +- Use AI image generation when a suitable existing asset is not already present. +- Match the visual style of recent generated blog covers in `images/`, including + the topic-specific illustration, simple composition, and readable 800x400 + treatment. +- Store cover images in `images/`. +- Use `cover_image: /images/filename.ext` in front matter. +- SVG is preferred when the cover is simple and generated as code; PNG or JPG is + fine for raster artwork. +- Recommended dimensions are 800x400. +- Keep file size modest; under 50 KB is preferred when practical. +- The post layout uses the page title as cover image alt text. + +## Styling + +- Custom styles live in `public/css/custom.scss`. +- The site uses SCSS through Jekyll compilation. +- Existing responsive breakpoints include 768px for tablet and 480px for mobile. +- Cover images have responsive sizing and hover effects; preserve that behavior + unless the user asks for a design change. + +## Listing Pages + +When creating or editing posts, verify that the article works in all three +public contexts: + +- Home page post listing: `index.html` uses `summary:` or `description:` before + falling back to body text. +- Archive listing: `archive/index.md` shows the post date and truncated title. +- Individual post page: `_layouts/post.html` renders `cover_image`, title, date, + and full content. + +Use a concise `summary:` so the home page does not leak large code blocks or +overly long paragraphs. + +## Local Development + +Prefer running the Jekyll server for visual checks: + +```bash +bundle exec jekyll serve --host=localhost --livereload +``` + +For drafts: + +```bash +bundle exec jekyll serve --drafts --host=localhost --livereload +``` + +Then inspect: + +- `http://localhost:4000/` +- `http://localhost:4000/archive/` +- the post URL + +During local development, images may fail if opened directly with `file://` and +absolute paths such as `/images/example.svg`. Use the Jekyll server for reliable +testing. + +## Visual QA + +- Test representative widths when changing post layout or cover-image CSS: + 375px mobile, 768px tablet, and 1200px or wider desktop. +- Confirm cover images scale without cropping important content. +- Confirm posts without cover images still render normally. +- Confirm the home page excerpt remains readable and compact. +- Confirm the archive title is not awkwardly truncated. + +## Site Structure + +```text +_posts/ Blog posts +_drafts/ Optional unpublished drafts +_layouts/ Jekyll layouts +_includes/ Jekyll includes +public/css/ SCSS stylesheets +images/ Blog post images +README.md Human maintainer workflow +AGENTS.md AI agent workflow +``` diff --git a/README.md b/README.md index 6bd1617..23e3c21 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,62 @@ Notes: - `` is optional; use it when you want the per‑post page to show a short intro before the rest. - Old posts don’t need to be edited. They’ll automatically use their first paragraph. +## Blog post publishing workflow + +New article drafts should normally start with `published: false` in the post +front matter so they can be reviewed safely on a branch or pull request. + +Recommended front matter for new posts: + +```yaml +--- +published: false +layout: post +title: My Post +description: A concise SEO description. +summary: A concise home-page teaser. +cover_image: /images/my-post-cover.svg +tags: +- dotnet +- csharp +--- +``` + +Before publishing, decide the publication date and make the filename match it: + +```text +_posts/YYYY-MM-DD-post-slug.md +``` + +If a post has an explicit `date:` field in front matter, keep it aligned with +the filename date. When the article is ready to go live, remove +`published: false` or change it to `published: true`, then merge the pull +request. + +After merging, GitHub Pages normally rebuilds automatically. If a manual rebuild +is needed, use the GitHub CLI from an authenticated checkout of this repository: + +```bash +gh api --method POST repos/solrevdev/solrevdev.github.io/pages/builds +``` + +For visual checks, run the site locally and inspect the article in all of the +places readers will see it: + +```bash +bundle exec jekyll serve --drafts --host=localhost --livereload +``` + +Then check: + +- `http://localhost:4000/` +- `http://localhost:4000/archive/` +- the individual post URL + +The home page uses `summary:` first, then `description:`, then the first real +paragraph. Keep `summary:` concise so the listing stays readable and does not +expose large code blocks. + ## SEO Improvements