From 77a2a03a815492ef52541257edaf4dabf93c05ba Mon Sep 17 00:00:00 2001 From: Oleg Proskurin Date: Mon, 5 Jan 2026 11:31:05 +0700 Subject: [PATCH] feat: new version --- .../docs/guides/placeholder-images/page.tsx | 702 ++++++++++++++++++ .../components/docs/shared/LivePreview.tsx | 32 + inbox/task-placeholder-guide-revision.md | 267 +++++++ 3 files changed, 1001 insertions(+) create mode 100644 apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx create mode 100644 apps/landing/src/components/docs/shared/LivePreview.tsx create mode 100644 inbox/task-placeholder-guide-revision.md diff --git a/apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx b/apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx new file mode 100644 index 0000000..fead8d0 --- /dev/null +++ b/apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx @@ -0,0 +1,702 @@ +import type { Metadata } from 'next'; +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { LivePreview } from '@/components/docs/shared/LivePreview'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { JsonLd } from '@/components/seo/JsonLd'; +import { createDocsMetadata, DOCS_PAGES } from '@/config/docs-seo'; +import { createBreadcrumbSchema, createTechArticleSchema } from '@/config/docs-schema'; +import { Hero, SectionHeader, InlineCode } from '@/components/docs/blocks'; + +const PAGE = DOCS_PAGES['guide-placeholder-images']; + +export const metadata: Metadata = createDocsMetadata(PAGE); + +const breadcrumbSchema = createBreadcrumbSchema([ + { name: 'Home', path: '/' }, + { name: 'Documentation', path: '/docs/' }, + { name: 'Guides', path: '/docs/guides/' }, + { name: 'Placeholder Images', path: '/docs/guides/placeholder-images/' }, +]); + +const articleSchema = createTechArticleSchema(PAGE); + +const tocItems = [ + { id: 'what-this-guide-covers', text: 'What This Guide Covers', level: 2 }, + { id: 'ai-generation-basics', text: 'AI Generation Basics', level: 2 }, + { id: 'quick-start', text: 'Quick Start', level: 2 }, + { id: 'organizing-placeholders', text: 'Organizing Placeholders', level: 2 }, + { id: 'prompt-tips', text: 'Prompt Tips', level: 2 }, + { id: 'avatar-placeholder', text: 'Avatar Placeholder', level: 2 }, + { id: 'product-image', text: 'Product Image', level: 2 }, + { id: 'hero-section', text: 'Hero Section', level: 2 }, + { id: 'og-image', text: 'OG Image', level: 2 }, + { id: 'features-block', text: 'Features Block', level: 2 }, + { id: 'file-based-workflow', text: 'File-based Workflow', level: 2 }, +]; + +export default function PlaceholderImagesGuidePage() { + return ( + <> + + + + + + {/* What This Guide Covers */} +
+ + What This Guide Covers + +

+ This guide shows how to generate placeholder images with Banatie: +

+
    +
  • + Live URLs — embed AI-generated images directly + in HTML +
    • +
  • + Ready-to-use snippets — copy into your project + with Tailwind classes +
    • +
  • + File download — save images locally via API +
    • +
+

+ All examples use real Live URLs. Images you see on this page are generated by Banatie. +

+
+ + {/* AI Generation Basics */} +
+ + AI Generation Basics + +

+ Banatie generates images from text descriptions. Key concepts: +

+ +
+
+

Prompt → Image

+

+ Describe what you need. The AI generates a matching image. +

+
+ +
+

Prompt Enhancement

+

+ Short prompts are automatically expanded. "office" becomes a detailed + description with lighting, composition, and style. +

+
+ +
+

Templates

+

+ Control visual style with the template parameter: +

+
    +
  • + photorealistic — photo-like images +
    • +
  • + digital-art — stylized illustrations +
    • +
  • + 3d-render — 3D graphics +
    • +
+
+ +
+

Caching

+

+ Same prompt returns the same image. First request generates, subsequent requests + serve from cache instantly. +

+
+
+
+ + {/* Quick Start */} +
+ + Quick Start + +

Basic Live URL format:

+ + +

Minimal example:

+ `} + language="html" + filename="Basic Usage" + /> + +

Parameters:

+ prompt, 'Yes', 'Image description (URL-encoded)'], + [ + aspectRatio, + 'No', + 'Ratio like 1:1, 16:9, 4:3 (default: 16:9)', + ], + [template, 'No', 'Style template name'], + ]} + /> + +

+ For full parameter reference, see{' '} + + Live URLs documentation + + . +

+ + + {/* Organizing Placeholders */} +
+ + Organizing Placeholders + +

Use scopes to group related images:

+ + +

+ Scopes are created automatically on first use. Each scope maintains its own cache. For + scope configuration and limits, see{' '} + + Live URLs → Scopes + + . +

+
+ + {/* Prompt Tips */} +
+ + Prompt Tips + + +
+
+

Be specific

+ +
+ +
+

Dark mode

+

Include theme context in your prompt:

+ +
+ +
+

Consistent style

+

+ Use the template parameter for visual consistency across + multiple images: +

+ +
+
+ +
+ + All examples in this guide use prompt enhancement. Your short descriptions are + automatically expanded into detailed prompts. + +
+
+ + {/* Avatar Placeholder */} +
+ + Avatar Placeholder + +

+ Aspect ratio: 1:1 +

+

+ Use case: User profiles, team sections, + testimonials. +

+ + + Testimonial Card + + +
+
+ Sarah Chen +
+

+ “Banatie cut our design mockup time in half. No more hunting for stock + photos.” +

+

Sarah Chen

+

Product Designer at Acme

+
+
+
+ + +
+ `} + language="html" + filename="Avatar Code" + /> +
+ + + Team Grid + + +
+
+ Alex Rivera +
+

Alex Rivera

+

Engineering Lead

+
+
+
+ Maria Santos +
+

Maria Santos

+

Design Director

+
+
+
+ James Wilson +
+

James Wilson

+

Product Manager

+
+
+
+ +
+ + {/* Product Image */} +
+ + Product Image + +

+ Aspect ratio: 1:1{' '} + (square) or 4:5 (portrait) +

+

+ Use case: E-commerce catalogs, product cards, + listings. +

+ + + Product Card + + +
+ Wireless Pro Headphones +

Wireless Pro Headphones

+

$299

+ +
+ + +
+ `} + language="html" + filename="Product Image Code" + /> +
+ + + Product Grid + + +
+
+ Smart Watch X1 +

Smart Watch X1

+

$199

+
+
+ AirPods Pro +

AirPods Pro

+

$249

+
+
+ Portable Speaker +

Portable Speaker

+

$79

+
+
+ Laptop Stand +

Laptop Stand

+

$129

+
+
+ +
+ + {/* Hero Section */} +
+ + Hero Section + +

+ Aspect ratio: 16:9 +

+

+ Use case: Landing page heroes, section + backgrounds, feature highlights. +

+ + +
+ Hero background +
+

Build the Future

+

+ Start your next project with AI-powered tools +

+
+
+ + +
+ + Hero background +
+

Your Headline

+
+
`} + language="html" + filename="Hero Section Code" + /> + +
+ + {/* OG Image */} +
+ + OG Image + +

+ Aspect ratio: 1200:630{' '} + (standard for social media) +

+

+ Use case: Social sharing previews, + Twitter/LinkedIn cards. +

+ + +
+
+
+ + + +
+ twitter.com +
+
+ OG Image Preview +

banatie.app

+

AI Placeholder Images Guide | Banatie

+

+ Generate AI placeholder images for development... +

+
+
+ + +
+ + + + + +`} + language="html" + filename="OG Meta Tags" + /> +
+ +
+ + OG images are crawled once and cached by social platforms. Change the prompt to + generate a new image for updated content. + +
+
+ + {/* Features Block */} +
+ + Features Block + +

+ Aspect ratio: 1:1 +

+

+ Use case: Feature grids, benefit sections, + service highlights. +

+ + +
+

Why Choose Us

+
+
+
+ Lightning Fast +

Lightning Fast

+

Deploy in seconds with our global CDN

+
+
+ Secure by Default +

Secure by Default

+

Enterprise-grade security built in

+
+
+ Easy Integration +

Easy Integration

+

Works with your existing stack

+
+
+ + +
+ +
+ Feature +

Feature Title

+

Feature description goes here.

+
+ +
`} + language="html" + filename="Features Grid Code" + /> + +
+ + {/* File-based Workflow */} +
+ + File-based Workflow + +

+ Sometimes you need image files in your repository instead of URLs. +

+ + + When to Use Files + +
    +
  • + Next.js projects with /public folder +
    • +
  • Static site generators requiring local assets
    • +
  • Version-controlled images
    • +
  • Offline development
    • +
+ + + API Generation + Download + +

+ Generate an image and save it locally: +

+ + + +

+ For full API reference, see{' '} + + Generations API + + . +

+
+ + + ); +} diff --git a/apps/landing/src/components/docs/shared/LivePreview.tsx b/apps/landing/src/components/docs/shared/LivePreview.tsx new file mode 100644 index 0000000..027a0c5 --- /dev/null +++ b/apps/landing/src/components/docs/shared/LivePreview.tsx @@ -0,0 +1,32 @@ +'use client'; + +interface LivePreviewProps { + children: React.ReactNode; + label?: string; + className?: string; + showLabel?: boolean; +} + +export const LivePreview = ({ + children, + label = 'Live Example', + className = '', + showLabel = true, +}: LivePreviewProps) => { + return ( +
+ {showLabel && ( +
+ + {label} + +
+ )} +
{children}
+
+ ); +}; diff --git a/inbox/task-placeholder-guide-revision.md b/inbox/task-placeholder-guide-revision.md new file mode 100644 index 0000000..b047381 --- /dev/null +++ b/inbox/task-placeholder-guide-revision.md @@ -0,0 +1,267 @@ +# Task: Revise Placeholder Images Guide + +**Priority:** High +**Type:** Content revision +**Related:** Previous guide implementation needs text/UX improvements + +--- + +## Context + +Guide exists at `/docs/guides/placeholder-images/page.tsx`. Structure is OK, but texts need revision based on review session. This task covers text changes and minor UX improvements. + +--- + +## SEO Keywords to Include Naturally + +Target these in headings and body text: +- "placeholder image url" (390/mo, KD 21) +- "html placeholder image" (320/mo, KD 33) +- "placeholder image generator" (480/mo, KD 32) +- "ai placeholder images" (from our research) + +--- + +## Section-by-Section Changes + +### Hero + +**Current subtitle:** "Generate contextual images for development. Copy-paste ready examples with Tailwind CSS." + +**New subtitle:** "Generate contextual images for development. The new era of AI placeholders." + +Remove Tailwind mention from hero — it's implementation detail, not selling point. + +--- + +### What This Guide Covers + +**Current:** +- Live URLs — embed AI-generated images directly in HTML +- Ready-to-use snippets — copy into your project with Tailwind classes +- File download — save images locally via API + +**New:** +- **Live URLs** — describe what you need right in `` src URLs +- **API generation** — full control, permanent URLs, downloadable files + +Remove "snippets" as separate point — that's expected from any guide. + +--- + +### AI Generation Basics → Rename to "How to Create Placeholders" + +**Current content:** Generic AI explanation (prompt → image, enhancement, etc.) + +**New content:** + +Focus on Banatie features, not AI basics: + +**Templates** +Choose a style, get quality results. Banatie enhances your simple prompt based on selected template. + +Available templates: +- `photorealistic` — photo-quality images +- `digital-art` — stylized illustrations +- `3d-render` — 3D graphics + +[Link to full templates documentation] + +**Simple Prompts** +Write minimal descriptions. Templates handle the rest. +- "office" → detailed modern office with proper lighting +- "headshot" → professional portrait with studio background + +No need for complex prompts — this is for placeholders, not art. + +**Remove:** +- "Prompt Enhancement" as separate concept (it's what templates do) +- "Caching" paragraph (belongs to Live URLs section, not here) + +--- + +### Quick Start + +**Add intro paragraph** explaining what Live URLs are and why they're perfect for placeholders: + +> Live URLs let you generate images by describing what you need right in the URL. No API calls, no file management — just an `` tag with your prompt. Each unique prompt is cached, so subsequent loads are instant via CDN. + +**Change example URL** from `{org}/{project}` placeholder to real working URL: + +```html +Mountain landscape +``` + +**Add live result** — show the actual generated image right after the code snippet. + +--- + +### Organizing Placeholders + +**Current:** Dry list of scope examples + +**New approach:** + +Short explanation: "Organize images by sections of your site using scopes." + +One example showing the pattern: +``` +/live/avatars?prompt=... → user photos +/live/hero?prompt=... → hero backgrounds +/live/products?prompt=... → product catalog +``` + +Then link: "Learn more about scopes in [Live URLs documentation](/docs/live-urls/#scopes)." + +Don't teach users how to name things — let them figure it out. + +--- + +### Prompt Tips + +**Current "Be specific"** — contradicts placeholder philosophy + +**New "Write less, not more":** + +> For placeholders, simple prompts work best. Templates add the details. +> +> - Want an office? Write "office" +> - Need something specific? Add only what matters: "office dark theme" +> - Templates handle lighting, composition, style + +**Current "Dark mode"** → **"Colors and themes":** + +> Control the mood with color hints: +> - `dark background` — dark theme +> - `blue and orange accents` — specific palette +> - `warm lighting` — cozy feel + +Keep dark mode examples but expand to general color control. + +**Remove "Consistent style"** — too vague. Consistency comes from templates + references (advanced topic). + +**Change TipBox text:** +From: "All examples in this guide use prompt enhancement..." +To: "Templates automatically enhance your prompts. A simple description becomes a detailed generation instruction." + +--- + +### Recipes Section + +**Add section header:** Create a parent heading "Recipes" or "Common Use Cases" that groups all the examples (Avatar, Product, Hero, OG, Features). + +--- + +### Recipe Cards: Code + Preview + +**UX improvement:** Each recipe should have a tabbed component with "Preview" and "Code" tabs, not separate blocks. + +If tabs are complex to implement, at minimum: +- Show live preview FIRST +- Code snippet below with clear label +- Remove redundant "Code Snippet" / "Live Example" headings — visual separation is enough + +--- + +### Testimonial Card (Avatar section) + +**Current design:** Basic dark card + +**Improve design quality:** +- Add subtle border or gradient +- Better typography hierarchy +- Proper quote styling (quotation marks or left border) +- Make it look like something you'd actually ship + +This is our showcase — it should look good. + +--- + +### File-based Workflow + +**Current intro:** "Sometimes you need image files in your repository instead of URLs." + +**New intro:** "Need files in your repo? Here's how to download generated images." + +Warmer, more direct. + +**Remove "Static site generators" mention** — no SEO value, weak use case. + +**Keep:** +- Next.js with imports (fix the pattern — show `import` from `src/assets`, not `/public`) +- Version-controlled images + +**Simplify download example:** + +Current code is mini-SDK territory. Simplify to: + +```javascript +// 1. Generate image +const response = await fetch('https://api.banatie.app/v1/generations', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-API-Key': process.env.BANATIE_API_KEY, + }, + body: JSON.stringify({ prompt: 'modern office' }), +}); + +const { image } = await response.json(); +console.log(image.cdnUrl); // Download this URL via browser or curl +``` + +Remove the fs.writeFileSync part — that's SDK territory. User can download via browser. + +--- + +### "When to Use Files" List + +**Current:** +- Next.js projects with `/public` folder ❌ +- Static site generators requiring local assets ❌ +- Version-controlled images +- Offline development + +**New:** +- Next.js/React projects with local image imports +- Version-controlled placeholder assets +- Offline or CI/CD environments + +--- + +## Component Changes + +### LivePreview wrapper + +Current implementation is OK. No changes needed unless design quality is poor. + +### Code/Preview tabs + +If implementing tabs is too complex, skip for now. But note it as future improvement. + +--- + +## Quality Checklist + +After implementation: +- [ ] No mention of "Prompt Enhancement" as standalone feature +- [ ] Templates positioned as primary feature +- [ ] All example URLs use `sys/demo` (real project) +- [ ] Quick Start shows actual generated image +- [ ] File-based section uses import pattern, not /public +- [ ] No static site generators mentioned +- [ ] Testimonial card looks professional +- [ ] SEO keywords naturally integrated + +--- + +## Files to Modify + +``` +apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx +``` + +No new files needed.