How to use this library

This page explains how the Testing Academy is organized and the conventions every page follows. For content authors, it also covers the page template and the Screenshot component.

Reader conventions

Page template

Every substantive Academy page follows this structure:

Intro paragraph: one or two sentences on what the page covers and why it matters.
Before you start (optional): prerequisites, and links to concepts you need first.
Definition / concept: what it is, and how it fits in the bigger picture.
How to do it in MaxoPerf: concrete steps in the console, or a real config snippet.
How to read the results: what to look for after a run (charts, metrics, indicators of pass/fail).
Do / don’t: quick guidance for this topic.
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, each with one fixed 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, because they break when pages move. To link to a concept in the existing docs portal, use /docs/concepts/… or /docs/how-to/….

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 short and show only what the point needs.

Screenshot placeholders

Screenshots show key moments in the MaxoPerf console. While a page is being written, each screenshot is a placeholder: a captioned dashed box with a stable id. TASK-1044 captures the real images and wires them 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. Check the plan before you add a new screenshot. 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. That is a one-line change per usage, with 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 fills the <title> tag, the sidebar label and the H1. Do not repeat it in the body.
description fills the <meta name="description"> tag. Keep it specific, and mention MaxoPerf where it reads naturally.
sidebar.order sets the sidebar position within the directory. Each directory has its own order sequence, starting at 1.
lastUpdated: update it 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 that are already in the SEO /glossary collection. The Academy glossary teaches the term and links to the SEO glossary card.
Do not change the URL or file name of an existing Academy page without updating all internal links. Search for every reference before you rename.
Do not add images with 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.