Best Practices

Content Editing

• Use the ACF flexible content sections to build pages. Each section type (hero, copy, cards, find-a-provider, etc.) is designed to work together and maintain visual consistency.
• Don't paste from Word or Google Docs without cleaning the formatting first. Use "Paste as plain text" or paste into a plain text editor first, then into WordPress. Rich text paste brings hidden markup that breaks styling.
• Preview before publishing. Use the WordPress preview button to check how content looks on the live site before hitting Publish.
• Keep titles concise. Page and post titles should be clear and descriptive — they're used in navigation, search results, and meta tags.

SEO

Yoast SEO is installed and handles meta tags, sitemaps, and schema markup.

• Fill in the Yoast fields on every page and post — focus keyphrase, meta description, and SEO title. If these are blank, Yoast auto-generates them, which is usually less effective.
• Use a single H1 per page. The page title is the H1. Don't add additional H1s in the content — use H2 and H3 for subheadings.
• Write descriptive alt text for images. This helps both SEO and accessibility. Describe what's in the image, not just "photo" or "image."
• Internal linking matters. Link between related providers, services, and life stages where it makes sense. This helps both users and search engines understand the site structure.
• Don't change URLs without setting up a redirect. The Redirection plugin handles this — if a page slug changes, add a redirect from the old URL to the new one.

Images

• Upload at the right size. WordPress generates multiple sizes from the original, but uploading a 5000px image for a 400px card wastes storage and bandwidth. Aim for 2x the display size (e.g., 800px wide for a 400px container).
• Use JPG for photos, PNG for graphics with transparency, SVG for icons. WebP is preferred when available.
• Media is automatically offloaded to S3 via the yax-offload-media plugin. You don't need to do anything special — upload through wp-admin as normal.

Provider Content

• Provider photos should be consistent — same background, similar framing, professional quality. They appear in cards and detail pages across the site.
• Keep bios current. When providers join, leave, or change specialties, update their posts promptly. The provider listing is one of the most-visited parts of the site.
• Ratings sync from Doctor.com automatically via the wha-doctorcom-sync plugin. Don't manually edit rating data.

General

• Don't install plugins without checking with the developer first. New plugins can conflict with existing functionality, break the build, or introduce security issues.
• Don't edit theme files through the WordPress editor. File editing in wp-admin is disabled for security reasons. All code changes go through version control.
• Report issues clearly. When something looks wrong, note the URL, what you expected to see, and what you actually see. Screenshots help.