|
| 1 | +# GitHub Copilot Instructions |
| 2 | + |
| 3 | +This file provides guidance to GitHub Copilot when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a Jekyll-based blog hosted on GitHub Pages, using the Neo-HPSTR theme. The site belongs to Micah Rairdon (Tiberriver256) and primarily focuses on PowerShell, software development, and technology topics. |
| 8 | + |
| 9 | +## Technology Stack |
| 10 | + |
| 11 | +- **Jekyll 3.9.0** - Static site generator |
| 12 | +- **GitHub Pages gem ~> 209** - Hosting platform |
| 13 | +- **Ruby** - Runtime environment |
| 14 | +- **Kramdown** - Markdown processor |
| 15 | +- **Neo-HPSTR Jekyll Theme** (customized) |
| 16 | + |
| 17 | +## Common Development Commands |
| 18 | + |
| 19 | +### Jekyll Development |
| 20 | +- **Local development**: `bundle exec jekyll serve` |
| 21 | +- **Build for production**: `bundle exec jekyll build` |
| 22 | +- **Install dependencies**: `bundle install` |
| 23 | + |
| 24 | +## Repository Structure |
| 25 | + |
| 26 | +### Content Organization |
| 27 | +- **Posts**: `_posts/` - Blog articles in markdown with YAML front matter |
| 28 | +- **Layouts**: `_layouts/` - HTML templates (post.html, page.html, post-index.html) |
| 29 | +- **Includes**: `_includes/` - Reusable components (head.html, header.html, footer.html, etc.) |
| 30 | +- **Assets**: `assets/css/` and `assets/js/` for stylesheets and JavaScript |
| 31 | +- **Images**: `images/` with subdirectories for each post's assets |
| 32 | +- **Configuration**: `_config.yml` contains site settings, owner info, and Jekyll configuration |
| 33 | + |
| 34 | +### Key Features |
| 35 | +- **Automatic OG image generation**: Uses Cloudinary API for dynamic social media images |
| 36 | +- **Giscus comments**: Integrated GitHub-based commenting system |
| 37 | +- **Search functionality**: JSON-based search via `search.json` |
| 38 | +- **RSS feed**: Generated at `/feed.xml` |
| 39 | +- **Google Analytics**: Configured with tracking ID G-4DS8LE3MB2 |
| 40 | + |
| 41 | +## Content Guidelines |
| 42 | + |
| 43 | +### Creating New Blog Posts |
| 44 | + |
| 45 | +1. **File naming**: `YYYY-MM-DD-title-slug.md` in `_posts/` directory |
| 46 | +2. **Required front matter**: |
| 47 | + ```yaml |
| 48 | + --- |
| 49 | + published: true |
| 50 | + layout: post |
| 51 | + title: "Your Title Here" |
| 52 | + description: "SEO description (150-160 chars max)" |
| 53 | + modified: YYYY-MM-DD |
| 54 | + tags: |
| 55 | + - Tag1 |
| 56 | + - Tag2 |
| 57 | + categories: |
| 58 | + - Category |
| 59 | + --- |
| 60 | + ``` |
| 61 | + |
| 62 | +### SEO Requirements |
| 63 | +- **Title**: 50-60 characters (6-10 words ideal) |
| 64 | +- **Description**: 150-160 characters maximum |
| 65 | +- **Tags**: 2-5 relevant tags maximum |
| 66 | +- **Keywords**: Include primary keyword naturally in title, description, and content |
| 67 | + |
| 68 | +### Content Structure Standards |
| 69 | +1. **Opening**: Hook the reader immediately |
| 70 | +2. **Problem/Context**: Clearly define what you're addressing |
| 71 | +3. **Solution/Content**: Provide detailed, actionable value |
| 72 | +4. **Conclusion**: Summarize key takeaways |
| 73 | + |
| 74 | +### Image Management |
| 75 | +- **Storage**: `images/[post-slug]/filename.ext` |
| 76 | +- **Reference in posts**: `{% include image.html path="filename.ext" alt="description" %}` |
| 77 | +- **Path format**: Filename only (not full URL or folder path) |
| 78 | +- Cloudinary handles automatic optimization and social media image generation |
| 79 | + |
| 80 | +## Code Style and Conventions |
| 81 | + |
| 82 | +### Writing Style (Strunk & White + Zinsser) |
| 83 | +- **Clarity over cleverness**: "Clear thinking becomes clear writing" |
| 84 | +- **Omit needless words**: Delete 10% of words each revision pass |
| 85 | +- **Active voice**: "Who does what?" structure |
| 86 | +- **Unity of design**: One paragraph = one topic |
| 87 | +- **Write to one reader**: Personal, conversational tone |
| 88 | +- **Read aloud**: Test for logic jumps and rhythm |
| 89 | + |
| 90 | +### Markdown Conventions |
| 91 | +- Use fenced code blocks with language specification |
| 92 | +- Keep paragraphs short and scannable |
| 93 | +- Use descriptive link text |
| 94 | +- Include alt text for all images |
| 95 | + |
| 96 | +## Configuration Files |
| 97 | + |
| 98 | +- **Main config**: `_config.yml` - Site settings, owner info, and Jekyll configuration |
| 99 | +- **Dependencies**: `Gemfile` - Specifies Jekyll 3.9.0 and github-pages ~> 209 |
| 100 | +- **Permalink structure**: `/:categories/:title/` |
| 101 | +- **Pagination**: 5 posts per page |
| 102 | + |
| 103 | +## Additional Resources |
| 104 | + |
| 105 | +For comprehensive writing guidelines, refer to: |
| 106 | +- `.github/instructions/writers-guide.instructions.md` - Detailed writer's guide |
| 107 | +- `.github/chatmodes/editor-review.chatmode.md` - Editorial review chatmode |
| 108 | +- `CLAUDE.md` - Claude-specific instructions |
| 109 | + |
| 110 | +## Guest Posts |
| 111 | + |
| 112 | +- Include attribution: `> Guest post authored by [Name](url). Additional context.` |
| 113 | +- Follow same SEO and content structure guidelines |
0 commit comments