CMS Best Practices

Provide expert guidance on Webflow CMS architecture, relationships, optimization, and troubleshooting.

Important Note

ALWAYS use Webflow MCP tools for all operations:

• Use Webflow MCP's webflow_guide_tool to get best practices before starting
• Use Webflow MCP's data_sites_tool with action list_sites to identify available sites
• Use Webflow MCP's data_sites_tool with action get_site to retrieve site details and plan limits
• Use Webflow MCP's data_cms_tool with action get_collection_list to analyze existing collections
• Use Webflow MCP's data_cms_tool with action get_collection_details to examine collection schemas
• Use Webflow MCP's data_cms_tool with action list_collection_items to assess content volume
• Use Webflow MCP's data_pages_tool with action list_pages to understand page structure
• Use Webflow MCP's ask_webflow_ai for specific API questions
• DO NOT use any other tools or methods for Webflow operations
• All tool calls must include the required context parameter (15-25 words, third-person perspective)

Instructions

Phase 1: Discovery & Analysis

1. Identify the request: Determine if user is:
   • Planning new CMS structure
   • Optimizing existing collections
   • Troubleshooting performance issues
   • Setting up relationships
   • Seeking architecture guidance
2. Get site information: Use Webflow MCP's data_sites_tool with actions list_sites and get_site to understand plan limits
3. Analyze existing structure: Use Webflow MCP's data_cms_tool with actions get_collection_list and get_collection_details to examine current setup
4. Assess content volume: Use Webflow MCP's data_cms_tool with action list_collection_items to understand scale
5. Review pages: Use Webflow MCP's data_pages_tool with action list_pages to see how content is displayed

Phase 2: Requirements Gathering

6. Understand use case: Ask clarifying questions:
   • What content needs to be managed?
   • Who will update the content?
   • How will content be displayed?
   • What relationships are needed?
   • Expected content volume?
7. Identify constraints: Consider plan limits, technical constraints, team skills
8. Define success criteria: Performance goals, editorial workflow, scalability needs

Phase 3: Architecture Planning

9. Design collection structure: Plan collections, fields, and relationships
10. Select field types: Choose appropriate field types for each content element
11. Plan relationships: Design one-to-many and many-to-many connections
12. Consider taxonomy: Determine categories, tags, and organizational structure
13. Plan for scale: Design for growth (pagination, performance, limits)
14. Document decisions: Explain tradeoffs and reasoning

Phase 4: Recommendations & Validation

15. Generate recommendations: Provide specific, actionable guidance
16. Prioritize changes: Organize by impact (quick wins vs. long-term)
17. Explain tradeoffs: Help users understand limitations and workarounds
18. Validate against best practices: Check against Webflow limitations and patterns
19. Provide alternatives: Offer multiple approaches when applicable
20. Create implementation roadmap: Break down into phases

Phase 5: Implementation Guidance

21. Provide step-by-step instructions: Clear guidance for implementation
22. Offer to assist: Suggest using other skills (cms-collection-setup, bulk-cms-update)
23. Document structure: Recommend documentation for team reference
24. Suggest testing approach: Guide on how to validate changes
25. Plan for migration: If refactoring, provide migration strategy

Collection Architecture

When to Use CMS vs Static

Use CMS when:

• Content updates frequently (weekly or more)
• Multiple similar items (blog posts, products, team members, projects)
• Non-technical users need to edit content
• Content needs filtering/sorting on the frontend
• Same content appears on multiple pages (author bios, product features)
• Content follows a consistent structure across items
• You need to dynamically generate pages

Use Static when:

• Content rarely changes (annual updates or less)
• Unique one-off sections (about page hero, homepage special features)
• Complex custom layouts per item that don't follow patterns
• No need for dynamic filtering or search
• Content is highly customized and doesn't share structure
• Performance is critical and content doesn't change
• You need complete design flexibility per section

Hybrid Approach:

• Static pages with CMS-driven sections (e.g., static homepage with CMS testimonials)
• CMS for recent content, static archives for old content
• Static landing pages, CMS for subpages

Field Type Selection

Content Type	Recommended Field	Notes	Character Limits
Short text	Plain Text	Titles, names, slugs	Max 256 chars
Long text (no formatting)	Plain Text (long)	Descriptions, excerpts	Unlimited
Formatted content	Rich Text	Blog content, bios, articles	Unlimited
Single image	Image	Photos, thumbnails, headers	4MB max per image
Multiple images	Multi-image	Galleries, product photos	Up to 25 images
File downloads	File	PDFs, documents, downloads	4MB max per file
Yes/No values	Switch	Featured flags, visibility toggles	Boolean
Single choice	Option	Status, type, category	Unlimited options
Date/time	Date/Time	Publish dates, events, deadlines	ISO 8601 format
Link to one item	Reference	Author → Post, Category → Post	One item
Link to multiple items	Multi-reference	Post → Tags, Post → Related Posts	Multiple items
External URL	Link	Social links, external resources	Max 2048 chars
Numeric values	Number	Prices, ratings, order, counts	Integer or decimal
Phone numbers	Phone	Contact numbers	E.164 format
Email addresses	Email	Contact emails	Valid email format
Color values	Color	Theme colors, accents, brand colors	Hex format
Video embeds	Video	YouTube, Vimeo embeds	Embed URL

Field Type Decision Tree

Need to store:
├── Text?
│   ├── Short (≤256 chars)? → Plain Text
│   ├── Long + Formatting? → Rich Text
│   └── Long + No Formatting? → Plain Text (long)
├── Media?
│   ├── Single image? → Image
│   ├── Multiple images? → Multi-image
│   ├── Video? → Video
│   └── File download? → File
├── Choice/Selection?
│   ├── Yes/No? → Switch
│   ├── One option? → Option
│   └── Link to item? → Reference/Multi-reference
├── Structured data?
│   ├── Number? → Number
│   ├── Date/Time? → Date/Time
│   ├── Phone? → Phone
│   ├── Email? → Email
│   └── URL? → Link
└── Visual?
    └── Color? → Color

Relationship Patterns

One-to-Many (Reference Field)

Example: Posts → Author

Authors Collection:
├── name (Text, required)
├── slug (Text, required)
├── bio (Rich Text)
├── photo (Image)
├── title (Text) - job title
├── email (Email)
└── social-links (Link)

Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── author (Reference → Authors)  ← Each post has ONE author

Display: On post page, access author.name, author.photo, author.bio

Filtering: Can filter posts by specific author

Advantages:

• ✅ Centralized author data (update once, reflects everywhere)
• ✅ Easy to maintain consistency
• ✅ Can create author profile pages showing all their posts
• ✅ Efficient (one reference per post)

Use cases:

• Blog posts → Author
• Products → Brand
• Events → Venue
• Projects → Client
• Testimonials → Customer

Many-to-Many (Multi-Reference)

Example: Posts ↔ Tags

Tags Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
└── color (Color) - optional visual grouping

Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── tags (Multi-Reference → Tags)  ← Each post has MANY tags

Display: On post page, loop through tags to show all tags

Filtering: Can filter posts by specific tag

Advantages:

• ✅ Flexible content organization
• ✅ Cross-linking related content
• ✅ Better SEO (topic clustering)
• ✅ Enhanced user navigation

Limitations:

• ⚠️ Max 5 multi-reference fields per collection
• ⚠️ Can only filter by ONE multi-reference value at a time in collection lists
• ⚠️ Cannot sort by referenced field values
• ⚠️ Each reference = additional query (impacts performance)

Workarounds for multiple tag filtering:

1. Create combined tags (e.g., "vegan-gluten-free")
2. Use Finsweet CMS Filter for client-side filtering
3. Create separate filtered collection lists for common combinations
4. Use custom code with Webflow API

Use cases:

• Blog posts ↔ Tags
• Products ↔ Features
• Projects ↔ Technologies
• Recipes ↔ Ingredients
• Courses ↔ Topics

Self-Reference (Nested Collections)

Example: Categories with subcategories

Categories Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
├── parent (Reference → Categories)  ← Self-reference for hierarchy
└── level (Number) - 1, 2, 3 for display logic

Use cases:

• Categories with subcategories
• Menu items with sub-menu items
• Organizational hierarchy
• Product taxonomy

Advantages:

• ✅ Flexible hierarchy
• ✅ Unlimited depth (theoretically)
• ✅ Easy to reorganize

Limitations:

• ⚠️ Complex to display nested levels in Webflow
• ⚠️ Max 2-3 levels recommended for practical implementation
• ⚠️ Requires custom logic for deep nesting

Alternative: Use Option field for simple 1-2 level categorization

Bidirectional Relationships

Example: Related Posts

Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── related-posts (Multi-Reference → Posts)  ← Self-reference to other posts

Display: Show related posts at bottom of post page

Advantages:

• ✅ Keeps users engaged longer
• ✅ Better SEO (internal linking)
• ✅ Flexible content connections

Challenges:

• ⚠️ Not truly bidirectional (A → B doesn't automatically create B → A)
• ⚠️ Must manually maintain both directions if needed
• ⚠️ Can be time-consuming for content editors

Solutions:

1. Use tags for automatic "related by tag" logic
2. Manual curation for most important connections
3. Hybrid: Manual + automated based on tags/category

Examples

Example 1: Planning New CMS Structure

User prompt:

I'm building a recipe site. How should I structure the CMS?

Step 1: Requirements Gathering

📐 CMS Planning: Recipe Site

Let me ask a few questions to design the best structure:

1. **Content Volume**: How many recipes do you plan to have?
   - Small (≤50): Simple structure
   - Medium (50-200): Moderate organization
   - Large (200+): Advanced taxonomy needed

2. **Recipe Attributes**: What information will each recipe have?
   - Basic: Name, ingredients, instructions, image
   - Advanced: Prep time, cook time, difficulty, nutrition, dietary tags

3. **Organization Needs**: How will users find recipes?
   - By meal type (breakfast, lunch, dinner)
   - By cuisine (Italian, Mexican, Asian)
   - By dietary restrictions (vegan, gluten-free, keto)
   - By cooking method (baking, grilling, slow cooker)
   - By ingredients (chicken, pasta, vegetables)

4. **Author Setup**: Single or multiple authors?
   - Single: You manage all content
   - Multiple: Team of recipe creators

5. **User Engagement**: What interactive features?
   - Comments/reviews
   - Ratings
   - Save favorites
   - Print recipe cards

Based on your answers, I'll design the optimal CMS architecture.

Step 2: After User Responds

📐 Recommended CMS Architecture: Recipe Site

Based on your requirements (Medium volume, Multiple authors, Advanced filtering):

---

## Collections Needed: 4

### 1. Recipes (Main Content)
├── name (Text, required) - "Homemade Pasta Carbonara"
├── slug (Text, required) - "homemade-pasta-carbonara"
├── description (Plain Text, 160 chars) - Brief summary for SEO
├── featured-image (Image) - Hero image for detail page
├── thumbnail-image (Image) - Smaller image for grid cards
├── prep-time (Number, required) - Minutes of prep
├── cook-time (Number, required) - Minutes of cooking
├── total-time (Number) - Auto-calculated or manual
├── servings (Number, required) - Number of servings
├── difficulty (Option: Easy, Medium, Hard)
├── ingredients (Rich Text, required) - Ingredient list with quantities
├── instructions (Rich Text, required) - Step-by-step directions
├── notes (Rich Text) - Cook's notes, tips, substitutions
├── nutrition-info (Plain Text) - Calories, protein, etc.
├── author (Reference → Authors, required)
├── category (Reference → Categories, required) - Primary meal type
├── cuisine (Reference → Cuisines) - Italian, Mexican, etc.
├── dietary-tags (Multi-Reference → Dietary Tags) - Vegan, GF, etc.
├── cooking-methods (Multi-Reference → Methods) - Baking, Grilling, etc.
├── featured (Switch) - Highlight on homepage
├── published-date (Date, required)
└── view-count (Number) - Track popularity

**Total fields:** 22 fields
**Plan required:** CMS plan minimum (20 collections, 2000 items)

### 2. Authors
├── name (Text, required)
├── slug (Text, required)
├── title (Text) - "Head Chef", "Recipe Developer"
├── bio (Rich Text)
├── photo (Image)
├── specialty (Plain Text) - "Italian Cuisine", "Baking"
├── social-instagram (Link)
├── social-website (Link)
└── email (Email)

**Purpose:** Reusable author information across all recipes

### 3. Categories
├── name (Text, required) - "Breakfast", "Lunch", "Dinner", "Desserts"
├── slug (Text, required)
├── description (Plain Text)
├── image (Image) - Category hero image
├── color (Color) - Brand color for UI
└── sort-order (Number) - Control display order

**Purpose:** Primary meal type classification

**Suggested Categories (8):**
- Breakfast & Brunch
- Appetizers & Snacks
- Lunch
- Dinner & Main Courses
- Side Dishes
- Salads
- Desserts & Sweets
- Drinks & Beverages

### 4. Cuisines
├── name (Text, required) - "Italian", "Mexican", "Asian"
├── slug (Text, required)
├── description (Plain Text)
└── flag-icon (Image) - Optional visual

**Purpose:** Filter by cuisine type

**Suggested Cuisines (12):**
- American, Italian, Mexican, Asian, Mediterranean, French, Indian, Thai,
  Chinese, Japanese, Greek, Middle Eastern

### 5. Dietary Tags
├── name (Text, required) - "Vegan", "Gluten-Free", "Keto"
├── slug (Text, required)
├── description (Plain Text)
├── icon (Image) - Badge icon
└── color (Color) - Badge color

**Purpose:** Multi-select dietary filters

**Suggested Tags (10):**