Building Sites

This guide covers best practices for building effective, maintainable, and performant sites with the Serverless CMS.

Before creating pages, plan your site structure:

1. Define page hierarchy: Identify top-level pages and their children
2. Choose page types: Determine which page types you need (Page, Article, Blog, custom)
3. Design templates: Create templates for each page type
4. Identify components: List the components you'll need

Example structure:

• Keep URLs short: /about not /about-our-company
• Use hyphens: /our-services not /our_services or /ourservices
• Avoid deep nesting: Limit to 2-3 levels maximum
• Be consistent: Use the same pattern throughout the site
• Plan for growth: Leave room for future pages

For general content pages:

Use for: About, Services, Contact pages

For news articles and blog posts:

Use for: Blog posts, news articles, case studies

For marketing and campaign pages:

Use for: Product pages, campaign pages, event pages

• Consistent headers/footers: Use fixed areas for elements that appear on every page
• Flexible content zones: Provide enough zones for varied content
• Logical flow: Order zones in a natural reading order
• Mobile-first: Design templates for mobile, then enhance for desktop
• Accessibility: Use semantic HTML and proper heading hierarchy

Choose the right components for your needs:

Build pages by composing components:

Example: About Page

1. Title: "About Our Company"
2. Rich Text: Company description
3. Image: Team photo
4. Rich Text: Mission statement
5. Teaser (×3): Team member profiles
6. Button: "Join Our Team"

Create custom components when:

• Built-in components don't meet your needs
• You need specialized functionality
• You want consistent branding across pages
• You need to integrate with external services

Examples:

• Product showcase
• Pricing table
• Contact form
• Video player
• Map embed

Define a consistent design system:

1. Set site theme: Configure design variables in site settings
2. Use in components: Reference variables in component CSS
3. Document standards: Create a style guide for content editors
4. Maintain consistency: Review pages regularly for consistency

Establish content guidelines for your team:

• Tone: Professional, friendly, conversational
• Voice: Active voice, second person ("you")
• Length: Concise, scannable paragraphs
• Formatting: Use headings, lists, and emphasis

• Titles: 50-60 characters, include target keyword
• Descriptions: 150-160 characters, compelling and descriptive
• Headings: Use H1 for page title, H2-H6 for sections
• Alt text: Descriptive, include keywords naturally

• Images: Always include alt text
• Links: Use descriptive link text ("Read our guide" not "Click here")
• Headings: Use proper heading hierarchy
• Color: Ensure sufficient contrast (WCAG AA: 4.5:1)

Establish a content workflow:

1. Draft: Author creates content
2. Review: Editor reviews for quality, SEO, accessibility
3. Revise: Author makes requested changes
4. Approve: Editor approves for publishing
5. Publish: User with publish permissions publishes
6. Monitor: Track performance and update as needed

• Format: Use WebP for photos, SVG for graphics
• Size: Resize images to display size (don't rely on CSS scaling)
• Compression: Compress images to reduce file size
• Alt text: Always include descriptive alt text

Recommended sizes:

• Hero images: 1920×1080 (or 16:9 ratio)
• Content images: 1200×800 (or 3:2 ratio)
• Thumbnails: 400×300 (or 4:3 ratio)

• Minimize components: Use only necessary components
• Avoid nesting: Don't nest containers unnecessarily
• Optimize CSS: Remove unused styles
• Limit animations: Use animations sparingly

The CMS uses aggressive caching:

• Static HTML: Cached with max-age=31536000, immutable
• CDN: CloudFront caches content globally
• Rebuild: Rebuild site to clear cache and apply changes

Design for mobile first, then enhance for larger screens:

1. Start with mobile: Design for 320px width
2. Add tablet styles: Enhance for 768px+ width
3. Add desktop styles: Enhance for 1024px+ width

Use platform breakpoints:

Test on multiple devices:

• Mobile: iPhone, Android phones (320-414px)
• Tablet: iPad, Android tablets (768-1024px)
• Desktop: Laptops, monitors (1280px+)

Use browser dev tools to test responsive behavior.

Follow WCAG 2.1 Level AA guidelines:

• Alt text: Provide alt text for all images
• Color contrast: Ensure 4.5:1 contrast ratio for text
• Text sizing: Allow text to scale to 200%

• Keyboard navigation: All interactive elements keyboard accessible
• Focus indicators: Visible focus indicators on all interactive elements
• Skip links: Provide skip-to-content links

• Clear language: Use plain language
• Consistent navigation: Keep navigation consistent across pages
• Error messages: Provide clear, helpful error messages

• Semantic HTML: Use appropriate HTML elements
• Valid HTML: Ensure HTML validates
• ARIA: Use ARIA attributes when semantic HTML is insufficient

• Keyboard: Navigate using only keyboard (Tab, Enter, Escape)
• Screen reader: Test with NVDA (Windows) or VoiceOver (Mac)
• Automated tools: Use axe DevTools or WAVE
• Manual review: Review for logical structure and clarity

• Sanitization: HTML is automatically sanitized on upload
• XSS prevention: Variable markers are HTML-encoded
• Input validation: All user input is validated

• Principle of least privilege: Grant minimum necessary permissions
• Regular audits: Review user access quarterly
• Deactivate promptly: Remove access when users leave

• Review logs: Monitor CloudWatch logs for suspicious activity
• Track changes: Review page version history
• Monitor crawlers: Track AI crawler activity

• Review new content: Check recently published pages
• Monitor analytics: Review page views and crawler activity
• Check for errors: Review error logs

• Update components: Check for component updates
• Review permissions: Audit user access
• Backup verification: Verify backups are working

• Content audit: Review all pages for accuracy and relevance
• Performance review: Check site performance metrics
• Security review: Review security settings and access logs
• Design review: Ensure design consistency across pages

When updating existing content:

1. Review current content: Understand what's currently published
2. Make changes: Edit in the page editor
3. Preview: Check the live preview
4. Test: Verify links, images, and formatting
5. Publish: Publish the updated page
6. Verify: Check the live page

Rebuild your site when:

• Theme changes: After updating design variables
• Template changes: After modifying templates
• Component updates: After uploading new component versions
• Periodic maintenance: Monthly or quarterly

Cause: CDN cache not cleared

Solution:

1. Perform a site rebuild
2. Wait 5-10 minutes for CDN cache to clear
3. Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)

Cause: Design variables not applied

Solution:

1. Check site theme settings
2. Rebuild site to apply variables
3. Clear browser cache

Cause: Page slug changed or page deleted

Solution:

1. Update links to use correct slugs
2. Restore deleted pages if needed
3. Set up redirects (contact administrator)

• Creating Sites — Create and configure sites
• Managing Templates — Design templates
• Creating Pages — Build pages
• Theming — Customize site appearance
• SEO Settings — Optimize for search engines