notque/vexjoy-agent / skills/content/content
content
UnverifiedContent operations: editorial calendar, marketing, publishing, social media management.
references/seo-guidelines.md
View on GitHub# SEO Guidelines Reference
## Length Requirements
### Title Tag
| Status | Character Count |
|--------|-----------------|
| Too short | < 30 chars |
| Suboptimal | 30-49 chars |
| Optimal | 50-60 chars |
| Too long | > 60 chars (truncated in SERPs) |
**Why it matters**: Search engines display ~60 characters in results. Truncated titles lose impact and may cut off key information.
### Meta Description
| Status | Character Count |
|--------|-----------------|
| Too short | < 120 chars |
| Suboptimal | 120-149 chars |
| Optimal | 150-160 chars |
| Too long | > 160 chars (truncated in SERPs) |
**Why it matters**: Descriptions are the "sales pitch" in search results. Too short wastes opportunity; too long gets cut off.
### URL Slug
| Status | Character Count |
|--------|-----------------|
| Optimal | 3-5 words |
| Acceptable | Up to 75 chars |
| Too long | > 75 chars |
**Why it matters**: Short, descriptive URLs are easier to share and may rank slightly better.
---
## Keyword Density
### Target Ranges
| Density | Assessment |
|---------|------------|
| 0-0.5% | Too low - keyword may not be recognized |
| 0.5-1% | Acceptable - natural usage |
| 1-2% | Optimal - good balance |
| 2-2.5% | Borderline - review for naturalness |
| 2.5-3% | Warning - likely over-optimized |
| > 3% | Critical - keyword stuffing territory |
### Calculation
```
Keyword Density = (Number of keyword occurrences / Total word count) * 100
```
### Counting Rules
- Count exact phrase matches: "hugo debugging" = 1 occurrence
- Partial matches don't count: "hugo" alone or "debugging" alone
- Variations count separately: "debug hugo" vs "hugo debugging"
- Headers count same as body text
- Alt text on images counts
---
## Header Hierarchy Best Practices
### Structure Rules
1. **H1**: Title only - exactly one per page
2. **H2**: Main sections - 3-7 is typical for blog posts
3. **H3**: Subsections within H2s
4. **H4+**: Rarely needed, use sparingly
### Common Mistakes
| Issue | Problem | Fix |
|-------|---------|-----|
| Multiple H1s | Confuses document structure | Use H2 for sections |
| Skipping levels | H1 -> H3 breaks hierarchy | Add H2 between |
| Too many H2s | Dilutes importance | Consolidate sections |
| No H2s | No clear structure | Add section headers |
### Keyword in Headers
- Primary keyword should appear in 1-2 H2s naturally
- Place keywords in headers where they fit naturally
- Variations are fine: "Debugging Hugo" vs "Hugo Debugging"
---
## Content Structure
### First Paragraph Requirements
- Should contain primary keyword within first 100 words
- Should establish what problem/topic the post addresses
- Should give reader reason to continue
### Ideal Blog Post Structure
```
Title (H1) - contains primary keyword
Introduction - primary keyword in first 100 words
Section 1 (H2) - optionally contains keyword
Content with natural keyword usage
Subsection (H3) if needed
Section 2 (H2) - primary keyword variation
Content
Section 3 (H2)
Content
Conclusion (H2)
Summary, call to action, internal links
```
---
## Internal Linking Best Practices
### Link Quantity
| Post Length | Recommended Links |
|-------------|-------------------|
| < 500 words | 1-2 internal links |
| 500-1500 words | 2-4 internal links |
| 1500-3000 words | 4-6 internal links |
| > 3000 words | 6-10 internal links |
### Anchor Text Rules
| Type | Example | Quality |
|------|---------|---------|
| Descriptive | "Hugo template debugging guide" | Best |
| Keyword-based | "debugging Hugo templates" | Good |
| Contextual | "I covered this in a previous post" | Acceptable |
| Generic | "click here", "read more" | Replace with descriptive anchor text |
| Naked URL | "https://example.com/post" | Replace with descriptive anchor text |
### Orphan Pages
- Every post should have at least one inbound internal link
- Posts with zero inbound links are "orphans"
- Orphans may not be discovered by search engines crawling the site
---
## Hugo/PaperMod Specifics
### Front Matter Fields for SEO
```yaml
---
title: "Primary Keyword: Descriptive Subtitle" # H1, appears in browser tab
date: 2024-12-24
description: "150-160 char meta description with primary keyword"
summary: "Short summary for list views (can match description)"
tags: ["keyword1", "keyword2"]
keywords: ["optional", "additional", "keywords"]
---
```
### PaperMod-Specific
- `summary`: Shows on list pages, home page
- `description`: Used for meta description in head
- If only `summary` is set, PaperMod may use it for both
- Set both for full control
### URL Structure
- Hugo creates URLs from filename by default
- `content/posts/2024-12-hugo-debugging.md` -> `/posts/2024-12-hugo-debugging/`
- Use lowercase, hyphens, include keyword in slug
---
## Technical Blog SEO Considerations
### What Works for Technical Content
- Specific, problem-focused titles ("Fix Hugo Build Error X")
- Code examples (searchable, shareable)
- Error messages as headers (people search exact errors)
- Version numbers when relevant ("Hugo 0.120+")
- Comparison posts ("X vs Y")
### Preferred Alternatives
- Use specific, problem-focused titles ("Fix Hugo Build Error X")
- Explain jargon when it is necessary
- Add date context when information changes over time
- Make the title match the content it leads to
- Keep language clear and aligned with the technical brand
### Long-Tail Keywords
Technical blogs often rank for long-tail keywords:
- "hugo template not found error" (specific error)
- "hugo partial not rendering" (specific symptom)
- "migrate from jekyll to hugo" (specific task)
These are often more valuable than generic terms like "hugo tutorial".
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |