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 index abcbadb..59cd517 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,73 @@ -# Repository Instructions +# AGENTS.md -## Blog Post Cover Images and SEO Metadata +Repository-specific guidance for AI agents working on this Jekyll blog. -When creating or updating a blog post, use the same cover-image pattern as recent posts: +## 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 +image: /images/post-cover.png +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. +- Avoid em dashes in new prose. Use commas, colons, parentheses, or separate + sentences. +- New posts should normally end with the established sign-off: + +```markdown +Success! 🎉 +``` + +## Cover Images and Social Images + +New technical posts should normally have both a visible SVG cover and a PNG +social image. 1. Create a deterministic SVG cover in `/images/`. - Use an 800x400 canvas. - - Match the existing style: simple full-canvas background, restrained gradients, terminal or tool UI motifs, clear title text, and a short subtitle. + - Match the existing style: simple full-canvas background, restrained + gradients, terminal or tool UI motifs, clear title text, and a short + subtitle. - Keep the SVG local, lightweight, and hand-editable. - Avoid remote image hosts. @@ -30,32 +91,93 @@ When creating or updating a blog post, use the same cover-image pattern as recen image: /images/example-cover.png ``` -5. Make sure each post has useful SEO front matter: - - ```yaml - title: Clear post title with the main topic - description: One concise search-friendly sentence describing the post. - summary: Optional longer summary for homepage excerpts. - tags: - - dotnet - - csharp - ``` - -6. Verify the generated HTML includes the expected metadata: +5. Verify the generated HTML includes the expected metadata: - canonical URL - `meta name="description"` - `og:image` using the PNG file - `twitter:card` set to `summary_large_image` - the PNG image is 1200x630 -7. Build before finishing: +Recommended visible cover dimensions are 800x400. The social PNG should be +1200x630 for reliable Open Graph and Twitter card previews. The post layout +uses the page title as cover image alt text. - ```bash - bundle exec jekyll build - ``` +## SEO Metadata -## Writing Style +- Every post should have an accurate `title`, `description`, `summary`, and + useful `tags`. +- Do not make SEO changes that are only keyword stuffing. Prefer accurate + titles, descriptions, tags, and useful cover/social metadata. +- Use a concise `summary:` so the home page does not leak large code blocks or + overly long paragraphs. + +## 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. + +## 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. + +Build before finishing: + +```bash +bundle exec jekyll build +``` + +## 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 -- Avoid em dashes in new prose. Use commas, colons, parentheses, or separate sentences. -- Keep technical writing practical and direct. -- Do not make SEO changes that are only keyword stuffing. Prefer accurate titles, descriptions, tags, and useful cover/social metadata. +```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