How to use this library

This page explains how the Testing Academy is organized, the conventions every page follows, and — for content authors — the page template and Screenshot component.

Reader conventions

Page template

Every substantive Academy page follows this structure:

1. Intro paragraph — one or two sentences: what this page covers and why it matters.
2. Before you start (optional) — prerequisites, links to concepts you need first.
3. Definition / concept — what it is; how it fits in the bigger picture.
4. How to do it in MaxoPerf — concrete steps in the console or a real config snippet.
5. How to read the results — what to look for after a run (charts, metrics, indicators of pass/fail).
6. Do / don’t — quick guidance specific to this topic.
7. Where to go next — links to related pages.

Index and overview pages (each section’s index.md) use a shorter template: section summary + reading order + links.

Callout types

The Academy uses Starlight’s built-in callout types with consistent meaning:

Type	When used
note	Extra context that is useful but not essential.
tip	A shortcut, time-saver, or best-practice nudge.
caution	Something easy to get wrong; proceed carefully.
danger	An action that can break a test or harm a target system.

Internal links

Every cross-link uses the full /docs/academy/… path. Do not use relative paths — they break when pages are moved. If you are linking to a concept in the existing docs portal, link to /docs/concepts/… or /docs/how-to/… as appropriate.

Code blocks

Taurus YAML, JMeter JMX snippets, and k6 JavaScript are shown in fenced code blocks with the language tag (yaml, xml, javascript). Keep snippets minimal — show only what is needed to illustrate the point.

Screenshot placeholders

Screenshots illustrate key moments in the MaxoPerf console. During authoring, screenshots are placeholders — a captioned dashed box with a stable id. Real images are captured in TASK-1044 and wired in by setting the src prop.

Importing the component

In any .mdx page, import Screenshot once at the top of the file (after the frontmatter):

import Screenshot from '@components/Screenshot.astro';

The @components alias resolves to apps/marketing-site/src/components/.

Using a placeholder

<!-- Screenshot to capture: id: foundations/run-overview-tab | shows: MaxoPerf run-detail Overview tab showing throughput and latency charts | caption: Console: Run detail → Overview tab. Shows throughput (RPS) and p95 latency charts for a finished run. -->

Props:

Prop	Required	Description
id	yes	Stable kebab-case id matching the screenshot plan (see docs/academy-screenshots-plan.md). Pattern: <area>/<descriptive-slug>.
alt	yes	Screen-reader alt text describing what the image shows. Write it as if the image were present.
caption	yes	Human-readable caption shown below the placeholder (and, when real, below the image). Describe the console state: what page, what action, what the reader should notice.
src	no	Omit now. TASK-1044 will supply the real image path.

Choosing an id

Every id must appear in docs/academy-screenshots-plan.md. Before adding a new screenshot, check the plan. If the shot you need is not listed, add it to the plan first with the console route and a clear description of what the shot must show — then use the new id in your content page.

Id format: <area>/<descriptive-slug>

Examples:

• foundations/run-overview-tab
• foundations/latency-percentile-chart
• cookbook/csv-data-entity
• test-types/stress-test-error-spike

When src is supplied (TASK-1044)

When TASK-1044 captures the screenshots, it sets src on each Screenshot component — a one-line change per usage, no content rewrite:

<!-- Screenshot to capture: id: foundations/run-overview-tab | shows: MaxoPerf run-detail Overview tab showing throughput and latency charts | caption: Console: Run detail → Overview tab. Shows throughput (RPS) and p95 latency charts for a finished run. -->

Frontmatter template

Copy this into every new Academy page:

---
title: <page title — sentence case, no trailing period>
description: <unique meta description, 1 sentence, mentions MaxoPerf where natural, ≤ 160 chars>
sidebar:
  order: <integer, unique within its directory; lower = earlier in the sidebar>
lastUpdated: 2026-06-07
---

• title — used in the <title> tag, sidebar label, and H1. Do not repeat it in the body.
• description — used in the <meta name="description"> tag. Keep it specific; mention MaxoPerf where it reads naturally.
• sidebar.order — controls the sidebar position within the directory. Each directory has its own independent order sequence starting at 1.
• lastUpdated — update this whenever you make a meaningful content change.

File naming

• Use kebab-case, all lowercase.
• File name = URL slug (Starlight derives the URL from the file name).
• No spaces, no underscores, no uppercase.
• Section index files: index.md (or index.mdx if the page needs MDX components).
• Non-index pages: descriptive noun phrase, e.g. latency-percentiles-deep-dive.mdx.

What not to do

• Do not add TBD, “coming soon”, or stub pages. Every page ships with real, substantial content (Done gate requirement).
• Do not redefine terms already in the SEO /glossary collection. The Academy glossary gives the learning treatment and cross-links to the SEO glossary card.
• Do not change the URL or file name of an existing Academy page without updating all internal links. Use search to find all references before renaming.
• Do not add images via direct <img> tags — always use the Screenshot component so TASK-1044 can capture and wire them in cleanly.

Where to go next

• Testing Academy hub — overview of all sections.
• Learning paths — find your recommended reading order.
• docs/academy-screenshots-plan.md — the SSOT of screenshot ids for TASK-1044.