mail_kbanc_com
/
nice-gee
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update all documentation to reflect current workflow and standards 

- Update MIGRATION_SUMMARY.md with current page count (15 pages)
- Update README.md with project stats and workflow references
- Create comprehensive WORKFLOW.md with complete claims page process
- Document strict image selection criteria
- Add quality checklists and troubleshooting guides
- Include file naming conventions and best practices
This commit is contained in:
kbanc85 2025-11-04 09:59:20 -05:00
parent 101be4601d
commit b2ec7fc805
3 changed files with 619 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
MIGRATION_SUMMARY.md
View File

@ -8,12 +8,14 @@ Successfully migrated your React SPA to Next.js with Static Site Generation (SSG
**Project Location:** `/Users/kamil/Desktop/Projects_Active/kbanc/kbanc-nextjs` **Project Location:** `/Users/kamil/Desktop/Projects_Active/kbanc/kbanc-nextjs`
**All Pages Converted:** 13 routes → 13 static HTML files **All Pages Converted:** 15 routes → 15 static HTML files
``` ```
✓ Homepage (/) ✓ Homepage (/)
✓ Claims Library Index (/claims-library) ✓ Claims Library Index (/claims-library)
✓ 8 Individual Claim Pages: ✓ 10 Individual Claim Pages:
- Amazon AI Playbook
- ChatGPT Features
- Vibe Hackathons - Vibe Hackathons
- Systems Thinking - Systems Thinking
- AI ROI Measurement - AI ROI Measurement
@ -54,7 +56,7 @@ Successfully migrated your React SPA to Next.js with Static Site Generation (SSG
## Build Output ## Build Output
All 13 pages generated as static HTML: All 15 pages generated as static HTML:
- Total build time: ~3 seconds - Total build time: ~3 seconds
- File size per page: ~30-35KB HTML - File size per page: ~30-35KB HTML
- All pages marked as static (○ symbol) - All pages marked as static (○ symbol)
@ -259,14 +261,15 @@ All necessary packages installed:
Build output confirms success: Build output confirms success:
``` ```
✓ Generating static pages (13/13) ✓ Generating static pages (15/15)
○ (Static) prerendered as static content ○ (Static) prerendered as static content
Route (app) Size First Load JS Route (app) Size First Load JS
┌ ○ / 184 B 106 kB ┌ ○ / 191 B 106 kB
├ ○ /claims-library 184 B 106 kB ├ ○ /claims-library 191 B 106 kB
├ ○ /claims-library/vibe-hackathons 184 B 106 kB ├ ○ /claims-library/amazon-ai-playbook 191 B 106 kB
└ ... [10 more routes] ├ ○ /claims-library/chatgpt-features 191 B 106 kB
└ ... [11 more routes]
``` ```
All pages marked with ○ = Static generation working perfectly! All pages marked with ○ = Static generation working perfectly!

21
README.md
View File

@ -9,11 +9,23 @@ Next.js site for kbanc.com with static site generation for optimal GEO (Generati
## Auto-Deployment ## Auto-Deployment
This repository is connected to Netlify. Every push to main branch triggers automatic deployment. This repository is connected to Netlify. Every push to main branch triggers automatic deployment.
## Project Stats
- **Total Pages:** 15 static HTML files
- **Claims Pages:** 10 individual claim articles
- **Build Time:** ~3 seconds
- **GEO Optimized:** ✅ Pre-rendered HTML + JSON-LD schema
## Documentation ## Documentation
### Setup & Deployment
- `MIGRATION_SUMMARY.md` - Technical migration details - `MIGRATION_SUMMARY.md` - Technical migration details
- `DOMAIN_SETUP_GUIDE.md` - Custom domain setup instructions - `DOMAIN_SETUP_GUIDE.md` - Custom domain setup instructions
- `NAMECHEAP_DNS_SETUP.md` - Complete DNS configuration - `NAMECHEAP_DNS_SETUP.md` - Complete DNS configuration
### Workflows
- `WORKFLOW.md` - Complete process for creating new claims pages
- `CLAIMS_PAGE_GUIDELINES.md` - Strict image selection criteria
## Local Development ## Local Development
```bash ```bash
npm install npm install
@ -27,3 +39,10 @@ npm run build
# Output: /out directory # Output: /out directory
``` ```
## Creating New Claims Pages
See `WORKFLOW.md` for the complete step-by-step process including:
- Extracting atomic claims from articles
- Strict image selection criteria (white bg, black text, red accents only)
- Required file updates (sitemap, components, CSV)
- Build and deployment checklist

588
WORKFLOW.md Normal file
View File

@ -0,0 +1,588 @@
# Complete Workflow for Creating Claims Pages
This document outlines the complete, step-by-step process for creating new claims pages optimized for Generative Engine Optimization (GEO).
---
## Overview
**Goal:** Create GEO-optimized claims pages that AI systems (ChatGPT, Claude, Perplexity) can easily extract and cite.
**Source Material:** Articles from AI Adopters Club (https://aiadopters.club)
**Output:** Static HTML pages with atomic claims, supporting evidence, and compliant infographics.
---
## Step 1: Select Source Article
### 1.1 Identify Article
- Browse AI Adopters Club for suitable articles
- Look for articles with:
- Concrete, measurable claims
- Statistics and data points
- Real-world case studies
- Actionable insights
### 1.2 Fetch Article Content
```bash
# Use WebFetch tool to extract article content
WebFetch(url: "https://aiadopters.club/p/article-slug")
```
**Extract:**
- Full article text
- All statistics and data points
- Key quotes from author
- Image URLs (for later filtering)
- Main thesis/conclusion
---
## Step 2: Extract Atomic Claims
### 2.1 Claim Requirements
Each claim must be:
- **Atomic:** Single, standalone statement
- **Concise:** 12-18 tokens (aim for ~15 words)
- **Verifiable:** Can be independently fact-checked
- **Specific:** Includes concrete numbers, names, or outcomes
- **Citable:** Formatted for LLM extraction
### 2.2 Create 5 Claims
Extract exactly **5 atomic claims** from the article.
**Good Examples:**
```
✅ "ChatGPT's file upload feature reduced a marketing director's weekly report preparation time from 3 hours to 20 minutes."
✅ "Amazon reduced warehouse operation costs 25% through AI-powered robotics implementation."
✅ "Custom GPTs reduce project plan preparation time by approximately 70%."
```
**Bad Examples:**
```
❌ "AI is helpful for businesses." (too vague)
❌ "Companies are seeing success with machine learning implementations across various departments." (not specific)
❌ "According to research, automation tools can save time and reduce costs significantly." (no concrete data)
```
### 2.3 Title Each Claim
Create a short, descriptive title for each claim:
- Format: "Category + Key Metric/Outcome"
- Examples:
- "File upload feature delivers 89% time reduction"
- "Custom GPTs accelerate project planning 70%"
- "Robotics deliver measurable cost reduction"
---
## Step 3: Select Compliant Images
### 3.1 Image Criteria (STRICT)
**See `CLAIMS_PAGE_GUIDELINES.md` for complete criteria.**
**ONLY include images that have ALL of these:**
- ✅ White background
- ✅ Black text (primarily)
- ✅ Red accent colors (symbols, headlines, highlights)
- ✅ Optional gray tones for secondary elements
- ✅ Text-heavy, informational content
**EXCLUDE images with:**
- ❌ Photographs
- ❌ Screenshots of software interfaces
- ❌ Colored backgrounds (blue, green, etc.)
- ❌ Multiple colors beyond white/black/red/gray
- ❌ Promotional graphics
### 3.2 Download Compliant Images
```bash
# Download only infographic-style images
curl -o public/assets/[descriptive-name].png "[image-url]"
```
**Naming convention:**
- Format: `[article-slug]-[description].png`
- Examples:
- `amazon-process-diagram.png`
- `chatgpt-career-leverage.png`
### 3.3 If No Compliant Images
**That's OK!** Create the claims page without images. The atomic claims and text content are sufficient for GEO.
---
## Step 4: Create Claims Page
### 4.1 Create Directory
```bash
mkdir -p src/app/claims-library/[article-slug]
```
### 4.2 Create Page File
Create: `src/app/claims-library/[article-slug]/page.tsx`
### 4.3 Page Structure Template
```typescript
import type { Metadata } from "next";
import Link from "next/link";
import { ArrowLeft, Linkedin, Youtube, Download } from "lucide-react";
export const metadata: Metadata = {
title: "[Article Title]",
description: "[Brief description of the 5 claims]",
authors: [{ name: "Kamil Banc" }],
openGraph: {
title: "[Article Title]",
description: "[Brief description]",
url: "https://kbanc.com/claims-library/[article-slug]",
type: "article",
},
twitter: {
card: "summary",
title: "[Article Title]",
description: "[Brief description]",
},
alternates: {
canonical: "https://kbanc.com/claims-library/[article-slug]",
},
};
// JSON-LD schema for SEO
const jsonLd = {
"@context": "https://schema.org",
"@type": "Article",
headline: "[Article Title]",
author: {
"@type": "Person",
name: "Kamil Banc",
jobTitle: "Author",
affiliation: {
"@type": "Organization",
name: "AI Adopters Club",
url: "https://aiadopters.club",
},
},
datePublished: "YYYY-MM-DD",
dateModified: "YYYY-MM-DD",
publisher: {
"@type": "Organization",
name: "AI Adopters Club",
url: "https://aiadopters.club",
},
description: "[Brief description]",
};
export default function [ComponentName]() {
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
<div className="min-h-screen bg-background">
{/* Header with back link */}
<header className="bg-muted border-b-2 border-border py-8 mb-12">
{/* ... header content ... */}
</header>
<main className="container max-w-3xl mx-auto px-6 pb-12">
{/* Atomic Claims section */}
<section className="mb-12">
<h2 className="text-3xl font-semibold mb-6 mt-12">Atomic Claims</h2>
{/* 5 claim cards */}
</section>
{/* Supporting Evidence section */}
<section className="mb-12">
<h2 className="text-3xl font-semibold mb-6 mt-12">Supporting Evidence</h2>
{/* Quote, statistics, images, sources */}
</section>
{/* CSV Download section */}
<section className="bg-muted border-2 border-accent rounded-lg p-8 mb-12 text-center">
{/* CSV download button */}
</section>
{/* Context section */}
<section className="bg-muted rounded-lg p-8 mb-12">
{/* Context about the claims */}
</section>
</main>
{/* Footer */}
<footer className="bg-muted border-t-2 border-border py-8 mt-12 text-center">
{/* ... footer content ... */}
</footer>
</div>
</>
);
}
```
### 4.4 Key Elements Required
1. **Metadata:** Complete SEO metadata with OpenGraph and Twitter cards
2. **JSON-LD Schema:** Embedded structured data for AI systems
3. **5 Atomic Claims:** Each in a styled card with title and statement
4. **Supporting Evidence:**
- Key quote from author
- Statistics section with 2-3 key metrics
- Compliant infographics (if available)
- Sources section with link to original article
5. **CSV Download:** Link to downloadable structured data
6. **Context Section:** Brief explanation of the claims and methodology
---
## Step 5: Create CSV File
### 5.1 Create CSV
Create: `public/assets/[article-slug]-claims.csv`
### 5.2 CSV Format
```csv
Claim Number,Claim Title,Claim Statement,Category,Supporting Evidence
1,[Claim Title],[Full claim statement],[Category],[Evidence source]
2,[Claim Title],[Full claim statement],[Category],[Evidence source]
3,[Claim Title],[Full claim statement],[Category],[Evidence source]
4,[Claim Title],[Full claim statement],[Category],[Evidence source]
5,[Claim Title],[Full claim statement],[Category],[Evidence source]
```
**Example:**
```csv
Claim Number,Claim Title,Claim Statement,Category,Supporting Evidence
1,File upload feature delivers 89% time reduction,ChatGPT's file upload feature reduced a marketing director's weekly report preparation time from 3 hours to 20 minutes,Productivity,Reported case study from AI Adopters Club research
```
---
## Step 6: Update Site Files
### 6.1 Update sitemap.xml
Add new page to `public/sitemap.xml`:
```xml
<url>
<loc>https://kbanc.com/claims-library/[article-slug]</loc>
<lastmod>YYYY-MM-DD</lastmod>
<changefreq>monthly</changefreq>
<priority>0.8</priority>
</url>
```
### 6.2 Update ClaimsLibrary Component
Add to `src/components/ClaimsLibrary.tsx`:
```typescript
{
title: "[Article Title]",
link: "/claims-library/[article-slug]"
}
```
**Position:** Insert near the top of the array (most recent first)
### 6.3 Update Claims Library Index Page
Add preview card to `src/app/claims-library/page.tsx`:
```typescript
{/* [Article Name] */}
<article className="bg-card border border-border rounded-lg p-8 mb-8 transition-shadow hover:shadow-lg">
<h3 className="text-xl font-semibold mb-4">
<Link
href="/claims-library/[article-slug]"
className="text-foreground hover:text-accent hover:underline transition-colors"
>
[Article Title]
</Link>
</h3>
<p className="text-muted-foreground mb-6 leading-relaxed">
[Brief description of the 5 claims]
</p>
<div className="flex flex-wrap gap-4 mb-6 text-sm text-muted-foreground">
<span className="px-3 py-1 bg-muted rounded"><span className="text-accent font-medium">5</span> Claims</span>
<span className="px-3 py-1 bg-muted rounded">Published: [Date]</span>
<span className="px-3 py-1 bg-muted rounded">Author: Kamil Banc</span>
</div>
<ul className="space-y-2 mb-6">
<li className="p-3 border-l-4 border-l-accent bg-muted text-sm">
[First claim preview]
</li>
<li className="p-3 border-l-4 border-l-accent bg-muted text-sm">
[Second claim preview]
</li>
<li className="p-3 border-l-4 border-l-accent bg-muted text-sm">
[Third claim preview]
</li>
</ul>
<Link
href="/claims-library/[article-slug]"
className="inline-flex items-center font-semibold text-accent hover:text-accent/80 transition-colors"
>
View All Claims →
</Link>
</article>
```
**Position:** Insert near the top, after any featured articles
---
## Step 7: Build and Test
### 7.1 Run Build
```bash
npm run build
```
**Expected output:**
```
✓ Generating static pages (16/16) # One more than before
○ (Static) prerendered as static content
Route (app) Size First Load JS
├ ○ /claims-library/[new-article-slug] 191 B 106 kB
```
### 7.2 Check for Errors
**Common issues:**
- Missing imports
- Incorrect image paths
- Syntax errors in JSX
- Missing metadata fields
**Fix errors and rebuild until successful**
### 7.3 Preview Locally (Optional)
```bash
npm run dev
# Visit http://localhost:3000/claims-library/[article-slug]
```
**Check:**
- All 5 claims display correctly
- Images load (if any)
- CSV download link works
- Links back to claims library
- Mobile responsive layout
---
## Step 8: Commit and Deploy
### 8.1 Stage Files
```bash
git add .
```
**Files that should be staged:**
- `src/app/claims-library/[article-slug]/page.tsx` (new)
- `public/assets/[article-slug]-*.png` (images, if any)
- `public/assets/[article-slug]-claims.csv` (new)
- `public/sitemap.xml` (modified)
- `src/components/ClaimsLibrary.tsx` (modified)
- `src/app/claims-library/page.tsx` (modified)
### 8.2 Commit Changes
```bash
git commit -m "Add [Article Title] claims page with infographics"
```
**Commit message format:**
- Use descriptive title
- Mention if infographics included
- Example: "Add ChatGPT Features claims page with infographics"
### 8.3 Push to GitHub
```bash
git push
```
**This triggers:**
- Automatic Netlify deployment
- Build process runs on Netlify
- Site updates within 1-2 minutes
### 8.4 Verify Deployment
1. Check GitHub Actions/Netlify deployment log
2. Visit: https://kbanc-nextjs.netlify.app/claims-library/[article-slug]
3. Test all functionality:
- Claims display correctly
- Images load
- CSV downloads
- Links work
- Mobile layout
---
## Quality Checklist
Before committing, verify:
### Content Quality
- [ ] Exactly 5 atomic claims
- [ ] Each claim is 12-18 tokens
- [ ] Each claim is independently verifiable
- [ ] Claims include specific data/metrics
- [ ] Quote from original author included
- [ ] 2-3 key statistics highlighted
- [ ] Link to original article in sources
### Images (if included)
- [ ] All images have white background
- [ ] All images use only black text
- [ ] All images use red for accents only
- [ ] No photographs included
- [ ] No screenshots included
- [ ] Images are text-heavy and informational
- [ ] Images saved to `/public/assets/`
- [ ] Images use descriptive filenames
### Technical
- [ ] Page builds without errors
- [ ] Metadata is complete (title, description, OG, Twitter)
- [ ] JSON-LD schema embedded
- [ ] CSV file created and linked
- [ ] sitemap.xml updated
- [ ] ClaimsLibrary component updated
- [ ] Claims library index page updated
- [ ] All links use correct href format
- [ ] Images use correct src paths
### SEO/GEO
- [ ] Canonical URL set correctly
- [ ] Meta description is compelling
- [ ] Title is optimized (<60 characters)
- [ ] JSON-LD includes all required fields
- [ ] Claims are in semantic HTML (not just styled divs)
- [ ] Page structure uses proper heading hierarchy
---
## File Naming Conventions
### Article Slugs
- Use lowercase
- Separate words with hyphens
- Keep short but descriptive
- Examples:
- `amazon-ai-playbook`
- `chatgpt-features`
- `vibe-hackathons`
### Image Files
- Format: `[article-slug]-[description].png`
- Use descriptive names
- Examples:
- `amazon-process-diagram.png`
- `chatgpt-career-leverage.png`
- `ai-roi-measurement-framework.png`
### CSV Files
- Format: `[article-slug]-claims.csv`
- Always include "-claims" suffix
- Examples:
- `amazon-ai-playbook-claims.csv`
- `chatgpt-features-claims.csv`
---
## Troubleshooting
### Build Fails
**Error:** `Module not found` or similar
**Fix:**
- Check all import paths
- Verify image files exist in `/public/assets/`
- Check for typos in filenames
### Images Don't Load
**Error:** 404 for image files
**Fix:**
- Images must be in `/public/` directory
- Use paths like `/assets/image.png` (no "public" in path)
- Rebuild after adding images
### Page Shows 404 After Deploy
**Error:** New page not found on live site
**Fix:**
- Verify build succeeded (check Netlify logs)
- Clear browser cache
- Wait 1-2 minutes for deployment to complete
### CSV Download Doesn't Work
**Error:** 404 when clicking download
**Fix:**
- Verify CSV file exists in `/public/assets/`
- Check href path in download link
- Rebuild if file was added after build
---
## Current Site Statistics
**As of last update:**
- Total pages: 15
- Claims pages: 10
- Build time: ~3 seconds
- Average page size: 191 B (+ 106 kB shared JS)
---
## Related Documentation
- **Image Guidelines:** `CLAIMS_PAGE_GUIDELINES.md`
- **Migration Details:** `MIGRATION_SUMMARY.md`
- **Domain Setup:** `DOMAIN_SETUP_GUIDE.md`
- **DNS Config:** `NAMECHEAP_DNS_SETUP.md`
---
## Quick Reference
### Complete File Checklist
Every new claims page requires changes to:
1. `src/app/claims-library/[slug]/page.tsx` (new file)
2. `public/assets/[slug]-claims.csv` (new file)
3. `public/assets/[slug]-*.png` (new files, if images)
4. `public/sitemap.xml` (add URL)
5. `src/components/ClaimsLibrary.tsx` (add entry)
6. `src/app/claims-library/page.tsx` (add preview card)
**Total files modified:** 4-6 depending on images
---
## Best Practices
### Do's ✅
- Always create exactly 5 claims
- Use specific numbers and metrics
- Include original article link
- Follow strict image criteria
- Test build before committing
- Write descriptive commit messages
- Verify deployment works
### Don'ts ❌
- Don't include vague claims
- Don't use screenshots as "infographics"
- Don't skip the CSV file
- Don't forget to update sitemap
- Don't commit without building first
- Don't include promotional images
- Don't use colored backgrounds in images
---
**Remember:** The goal is GEO optimization. Every decision should prioritize making content easily extractable and citable by AI systems.