Troubleshooting: Homepage Not Showing Posts

Issue

Homepage shows title/subtitle and view buttons, but no story tiles/posts.

Checklist

1. Verify Tag Slug

The tag slug must start with story- (lowercase, with hyphen).

✅ Correct: story-ai-companion ❌ Wrong: ai-companion, Story-AI-Companion, story_ai_companion

Check:

• Go to Tags in Ghost admin
• Find “AI Companion” tag
• Verify the slug is exactly story-ai-companion

2. Verify Post is Published

The post must be Published (not Draft or Scheduled).

Check:

• Go to Posts in Ghost admin
• Find your test post
• Status should be Published (green dot)
• If it says “Draft”, click Publish

3. Verify Post Has the Tag

The post must be tagged with your story tag.

Check:

• Edit your test post
• In the Settings panel (gear icon), check Tags
• Should show “AI Companion” or “story-ai-companion”
• If missing, add it

4. Verify Theme is Active

Make sure the Story theme is actually active.

Check:

• Go to Settings → Design
• Verify “Story Theme” is shown as Active
• If not, activate it

5. Check Browser Console

Open browser developer tools (F12) and check for JavaScript errors.

Check:

• Press F12 (or Cmd+Option+I on Mac)
• Go to Console tab
• Look for red errors
• Check Network tab to see if CSS/JS files are loading

6. Verify Tag Has Posts

The homepage only shows tags that have at least one published post.

Check:

• Go to Tags in Ghost admin
• Click on “AI Companion” tag
• Should show “1 post” or similar
• If it shows “0 posts”, the post isn’t properly tagged

Quick Test

1. Create a new test:
   • Create tag: Name Test Story, Slug story-test
   • Create post: Title Test Chapter, Tag it with story-test
   • Publish the post
   • Check homepage
2. Check the tag page directly:
   • Go to http://localhost:2368/tag/story-ai-companion/
   • If this works, the issue is with the homepage query
   • If this doesn’t work, the tag/post setup is wrong

Common Issues

Issue: Tag slug doesn’t match pattern

Solution: The slug must be exactly story-ai-companion (lowercase, hyphen, starts with story-)

Issue: Post is Draft

Solution: Change status to Published

Issue: Post not tagged

Solution: Edit post, add tag in Settings panel

Issue: Theme not active

Solution: Go to Settings → Design, activate Story Theme

Issue: CSS hiding content

Solution: Check browser console for errors, verify CSS is loading

Debug Steps

1. Check tag directly:

   http://localhost:2368/tag/story-ai-companion/
   

2. Check post directly:

   http://localhost:2368/[your-post-slug]/
   

3. Verify in Ghost admin:
   • Tags → “AI Companion” → Should show post count
   • Posts → Your post → Should show tag
4. Check theme template:
   • The homepage uses: ``
   • This should find any tag starting with “story-“

Still Not Working?

If none of the above works:

1. Rebuild theme:

   cd ghost-theme
   npm run build
   

2. Restart Ghost:

   docker-compose restart ghost
   

3. Clear browser cache:
   • Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
4. Check Ghost logs:

   docker-compose logs ghost | tail -50