Best Practices

Organization

Good organization makes Content Mode projects easier to maintain and scale.

Collection Names

• Use descriptive collection names that clearly indicate content type
• Use plural forms (e.g., "posts" not "post")
• Avoid generic names like "items" or "content"
• Use consistent naming conventions across your project

Content File Organization

• Organize content files logically within collection directories
• Use descriptive filenames that reflect content
• Keep filenames URL-safe (lowercase, hyphens, no spaces)
• Consider using nested directories for complex structures

Template Organization

• Keep templates organized in the templates/ directory
• Use descriptive template filenames
• Group related templates in subdirectories if needed
• Use includes for reusable components

Naming Conventions

• Use consistent naming across collections, fields, and templates
• Follow a pattern (e.g., kebab-case for files, camelCase for fields)
• Document your naming conventions for team consistency

Content Structure

Well-structured content is easier to manage and maintain.

Field Definitions

• Define required fields in collection configuration
• Use appropriate field types for validation
• Document field purposes and expected values
• Keep field definitions consistent across collections

Front Matter

• Use consistent front matter structure across content files
• Keep front matter organized and readable
• Include all required fields
• Use relations instead of duplicating data

Content Quality

• Write clear, well-structured Markdown
• Use headings to organize content
• Keep content focused and readable
• Use consistent formatting across files

Relations

• Use relations for linked content instead of duplicating data
• Reference relations by slug consistently
• Ensure referenced content exists
• Document relation structures

Templates

Well-designed templates are maintainable and performant.

Output Safety

• Use escaped output ($) for user content to prevent XSS
• Use raw output ($!) only for trusted HTML (like rendered Markdown)
• Always escape user-generated content
• Never trust user input without escaping

Error Handling

• Check for existence before accessing nested properties
• Use conditionals to handle missing data gracefully
• Use helpers.default() for fallback values
• Provide sensible defaults for optional content

Template Design

• Use includes for reusable components (headers, footers, etc.)
• Keep templates DRY (Don't Repeat Yourself)
• Use variables to simplify complex expressions
• Use helpers for formatting instead of manual manipulation

Maintainability

• Keep template logic simple and readable
• Document complex template logic
• Use consistent formatting and structure
• Break complex templates into smaller includes

Publishing

Effective publishing workflows keep content organized and manageable.

Draft Workflow

• Use drafts for work-in-progress content
• Set published: false for content not ready for publication
• Change to published when content is complete
• Review drafts regularly

Scheduling

• Schedule future content for time-sensitive releases
• Use ISO 8601 format for dates
• Use UTC timezone (Z suffix) for consistency
• Review scheduled content regularly to ensure dates are correct

Date Management

• Use consistent date formats across content
• Include dates for time-sensitive content
• Use UTC for scheduled dates to avoid timezone issues
• Document date format expectations

Content Review

• Review published content regularly
• Check scheduled content dates
• Archive or update outdated content
• Maintain content quality standards

Performance

Optimize Content Mode for faster builds and better performance.

Build Caching

• Enable build caching (automatic in Content Mode)
• Only changed files are re-parsed between builds
• Cache is automatically invalidated on file changes
• Don't manually clear cache unless necessary

Content Organization

• Organize content efficiently to minimize search time
• Use relative paths in larger projects for faster resolution
• Keep file structures logical and shallow when possible
• Avoid deeply nested directory structures

Template Optimization

• Keep template logic simple and efficient
• Avoid deeply nested loops when possible
• Use conditionals to skip unnecessary processing
• Minimize template complexity

File Formats

• Use appropriate file formats (Markdown for content, YAML for data)
• Keep content files focused and not overly large
• Optimize images and assets in the public directory

Workflow

Effective workflows make Content Mode projects more productive.

Content Creation

• Create content files with proper front matter structure
• Use the UI to manage publishing status
• Review content before publishing
• Use drafts for work-in-progress

Template Development

• Start with simple templates and add complexity gradually
• Test templates with sample content
• Use includes to build reusable components
• Iterate on template design based on content needs

Configuration Management

• Define collections before creating content
• Use field definitions for validation
• Document configuration decisions
• Review and update configuration as needs change

Testing

• Test builds regularly during development
• Check build logs for warnings
• Verify output paths are correct
• Test with different content scenarios

Summary

Following these best practices will help you:

• Build maintainable Content Mode projects
• Avoid common pitfalls and issues
• Optimize for performance and efficiency
• Create consistent, high-quality content-driven sites

Next Steps

Now that you understand best practices:

• Review Workflow Examples to see best practices in action
• Check Troubleshooting if you encounter issues
• Explore Advanced Features for more capabilities