Real Testimonials

Appearance

CLAUDE.md ​

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is ​

A VitePress documentation site for the Real Testimonials WordPress plugin (by ShapedPlugin LLC). It contains only Markdown docs, a small custom theme, and images — no plugin code.

Brand ​

  • Name: Real Testimonials
  • Primary color: #1E67D8 (blue)
  • Logo: Located in public/logo.svg (light mode) and public/logo-dark.svg (dark mode) — person silhouette with 5-star rating bubble icon

The site is documentation only (guide/): user-facing pages plus one developer page (guide/hooks.md, the Hooks reference). Feature behavior, setting names, block attributes and defaults are verified against the real plugin source — see below.

Reference: the plugin source ​

The actual plugin lives in a sibling directory on this machine:

/Users/th24/wordpress/real-testimonial/wp-content/plugins/testimonial-pro    # from docs repo: ../testimonial-pro

Read it before writing or editing docs — it is the ground truth. Verify feature behavior, setting names, block attributes, and defaults against the real code instead of guessing. Useful entry points:

  • testimonial-pro.php — main plugin file (version, bootstrap, sp_testimonial() helper)
  • src/ — PHP: src/Blocks/ (block registration, render), namespaced ShapedPlugin\TestimonialPro
  • src/Admin/Views/Framework/configs/metaboxs.php — the entire classic admin UI (Manage Views "Shortcode Options", Testimonial Forms "Form Options", Reviewer Information metabox): field titles, options, defaults, dependencies. Ground truth for every guide/classic/ page.
  • src/Frontend/Frontend.php — classic shortcode registration (sp_testimonial, sp_single_testimonial, sp_testimonial_form)
  • app/ — React admin/editor source
  • docs/ — the plugin's own internal docs
  • CLAUDE.md — the plugin repo's own instructions

Do not edit the plugin source from this repo — read-only reference. Keep it out of docs commits.

README.md is the human-facing GitHub readme (build commands + contributor notes). This file, CLAUDE.md, is the instructions for you — keep the two in sync when build commands change, but don't merge them.

Repo map ​

.vitepress/
  config.mjs          # site config: nav, sidebar, cleanUrls, ignoreDeadLinks, stampImageDimensions rule
  theme/              # custom theme (see "Custom theme" below)
guide/                # user docs
  *.md                # Getting Started: introduction, installation, requirements, quick-start, blocks-overview, add-new-testimonial; hooks.md = developer Hooks reference ("Developers" sidebar group)
  blocks/             # one page per block (display, social, child, form, shortcode); carousel.md is the canonical shared-panel reference
  classic/            # classic (shortcode) version: overview, manage-views, layout-presets, testimonial-forms — verify against metaboxs.php (see above)
  dashboard/          # admin dashboard: overview, blocks, modules, integrations, saved-templates, settings
public/images/<section>/  # WebP screenshots, served at web root; sections: getting-started/, blocks/ (nests form/, child-blocks/), features/ (carousel shared panels), classic/, dashboard/
public/logo.svg       # Real Testimonials logo (light mode)
public/logo-dark.svg  # Real Testimonials logo (dark mode)
index.md              # VitePress home page (layout: home)
SCREENSHOTS.md        # master screenshot checklist: capture specs + per-file captured/missing status

Commands ​

bash
npm install            # install deps
npm run docs:dev       # dev server + hot reload at http://localhost:5173
npm run docs:build     # static build into .vitepress/dist
npm run docs:preview   # serve the production build locally

There are no tests or linters. Run npm run docs:build to validate changes — the build is the source of truth for whether the site is correct.

ignoreDeadLinks: false in .vitepress/config.mjs. Any dead internal page link fails the build. Internal links are extensionless VitePress paths (/guide/blocks/grid, /guide/dashboard/settings) — cleanUrls is on. After renaming, moving, or removing a page or heading, run the build and fix every link that pointed at it.

Same-page #anchor links are NOT checked — a wrong in-page anchor builds fine and silently breaks. Heading slugs keep em dashes and collapse & (e.g. "Form Options — the tabs" → #form-options-—-the-tabs, "Status & Notifications" → #status-notifications, single hyphen). After adding in-page anchors, verify against the built HTML's id="..." attributes in .vitepress/dist.

Adding or moving a page ​

The sidebar and top nav are not automatic — they are hand-maintained in .vitepress/config.mjs under themeConfig.sidebar (the /guide/ group) and themeConfig.nav. Creating a Markdown file does nothing until you add it to the sidebar. Keep the sidebar order sensible for readers.

A page can also be reachable but hidden — present, linked inline from other pages, yet absent from the sidebar. So a page missing from the sidebar isn't automatically dead; grep for inline links before assuming it's orphaned. (Every guide page is currently in the sidebar, but that can change.) When you add a page, decide deliberately whether it belongs in the sidebar, only in inline links, or both.

Images ​

  • Live in public/images/<section>/. VitePress serves public/ at the web root, so reference them without the public prefix: /images/blocks/grid-editor.webp.
  • Format/spec: WebP, ~1600px wide, captured in light theme.
  • A custom markdown rule in config.mjs (stampImageDimensions, using the image-size dep) reads each local image at build time and stamps intrinsic width/height to prevent layout shift / broken anchor scrolling. The rule silently skips images it can't find — but the build itself fails on any live ![](...) ref whose file is missing from public/ (rollup can't resolve the asset). So never embed a not-yet-captured screenshot as a live ref: keep it as an HTML comment (<!-- ![alt](/images/...) -->) until the file exists.
  • Screenshot tracking: SCREENSHOTS.md maintains the master checklist. Mark items as complete (✅) when captured, and remove rows for files that get deleted from public/.

Voice & tone — write like a human, for beginners ​

Write every page as a seasoned product researcher and content writer with 5+ years of experience would. That means: you understand the product deeply, you know what a real user is actually trying to accomplish, you anticipate their questions and confusion, and you write clear, structured, empathetic docs — not a feature dump. Docs must read as if a friendly human wrote them for a first-time WordPress user. This is a hard requirement, not a preference.

  • Lead with the user's goal. Like a product researcher, open each page/section with the job the reader is trying to get done, then show the path. Anticipate the "but what about…" questions and answer them inline.
  • Write for a beginner. Assume the reader has never used this plugin and may be new to WordPress. Explain why a step matters, not just what to click. Never assume prior knowledge without a one-line explanation or a link.
  • Sound human, not AI. Use plain, conversational language and contractions ("you'll", "it's"). Vary sentence length. Read it aloud — if it sounds robotic or like a spec sheet, rewrite it.
  • Talk to the reader as "you." Use active voice and direct instructions ("Open the inspector", not "The inspector should be opened").
  • Define jargon on first use. The first time a term like block, inspector, shortcode, or taxonomy appears on a page, give a short plain-English gloss or link to where it's explained.
  • Concrete over abstract. Prefer real examples, numbered step-by-step walkthroughs, and screenshots over dense feature descriptions. Break walls of text into short paragraphs and lists.
  • Avoid AI/marketing tells. No "unleash", "seamlessly", "in today's digital landscape", "robust", "leverage", "delve", or empty hype. Don't over-hedge ("might possibly perhaps"). Say it directly.

Content conventions ​

  • One # H1 per page, immediately followed by a one-line > blockquote lead. Then ##/### sections.
  • guide/quick-start.md is a router page, not a tutorial. It holds three short steps: add testimonials (→ add-new-testimonial), pick a display path via two styled rt-path link cards (Blocks → blocks-overview, Classic → classic/overview), then a full-width card to the dashboard overview. The card markup/CSS lives inline in the page (<style scoped>). Detailed walkthroughs belong on the destination pages, not here.
  • guide/add-new-testimonial.md is shared by both paths. It sits in Getting Started (not classic/) because blocks and classic Views read the same testimonials; both blocks-overview and classic/overview link to it.
  • guide/blocks/carousel.md is the canonical shared-panel reference. Card designs, Query Builder, and inspector panels are identical across all display blocks, so Carousel documents every panel in full (with screenshots from public/images/features/) and other block pages document only their own Layouts panel, then link back to the Carousel anchors. When those shared panels change, update carousel.md and check the pages that link to it rather than duplicating the content.
  • index.md is the VitePress layout: home page (hero + feature grid in frontmatter).

Custom theme (.vitepress/theme/) ​

Extends the default VitePress theme; three additions worth knowing:

  • DocComments.vue — injects an external feedback widget (comments.rubelmiah.com) below each page, re-mounting on route change.
  • medium-zoom — click-to-zoom lightbox on every .vp-doc img except .no-zoom (home hero / logos).
  • hash-scroll fix in index.js — re-aligns #section anchors after images/fonts load (production builds otherwise mis-land deep links).

Deployment ​

Build output (.vitepress/dist, gitignored) deploys to any static host. Build command npm run docs:build; publish dir .vitepress/dist; production host https://docs.realtestimonials.io (set as the sitemap hostname).

Last updated: