Writing notes

A practical guide for writers and admins. Use this page when you are writing or editing notes: it covers the basic Markdown you need, the note structure we use, and every special block available on the site. It mirrors the live styling, so you can copy the markup here and adapt it.

The repo source of truth is how-to-write-notes.md; this page turns those rules into a writer-friendly reference.

---

Quick start

Every notes page is a Markdown file in astro/src/content/docs/notes/. A normal unit page should start with front matter, then go straight into the first real section.

---
title: "Page title"
sidebar:
  order: 1
---

## First Topic

Write the explanation here. Start with the idea before using formulas heavily.

<div class="theorem-box">

**Example.** A short problem statement that ends with what to find.

Show the work here.

</div>

---

## Practice

1. Practice question here.
2. Another practice question here.

The page title comes from title: in the front matter. Do not add a separate # Page title heading in the body. Start normal sections with ##.

Do not add an appendix unless someone explicitly asks for one. Put new formulas, examples, explanations, and practice directly into the section where a student would use them.

---

Markdown basics

Markdown is plain text with small symbols that turn into formatted content.

## Big Section

### Smaller Section

This is a paragraph. Leave a blank line between paragraphs.

- Bullet point
- Another bullet point

1. Numbered step
2. Another numbered step

**Bold important words.** Use *italics* for light emphasis.

[Link text](/notes/ap/calculus/limits/)

For lists, start each item with words before a formula. A bullet that begins with only math can render awkwardly.

- $$R = 8.314\ \text{J/(mol K)}$$ (WRONG!!!)
- Ideal gas constant: $$R = 8.314\ \text{J/(mol K)}$$ (Correct)

Use --- to separate large sections when it helps the page scan cleanly. Leave a blank line before and after section dividers, headings, theorem boxes, callout blocks, and images.

---

Math

Use $$...$$ for all math, including inline math. The notes site renders math with KaTeX.

Inline math looks like $$f'(x)$$ inside a sentence.

Display math gets its own lines:

$$
\frac{d}{dx}\sin x = \cos x
$$

Keep delimiters balanced: every $$, {, \left, and \begin{...} needs a matching close. For absolute value, use \lvert and \rvert instead of plain vertical bars, since bare | can confuse Markdown tables.

$$
\lvert x - 3 \rvert < 5
$$

---

Images

Use plain /assets/... paths. Include useful alt text, and keep the standard classes so images size consistently.

Leave exactly one blank line above and below every image block. This applies to both <img> tags and image-generating fenced code blocks such as TikZ; do not leave multiple empty lines around them.

<img class="note-img note-img--w480" src="/assets/Images/og-card.png" alt="Example figure" loading="lazy" decoding="async" />

Only add image placeholders when the diagram would materially help the note.

---

Callout directives

Authored as :::type{field="…"} … :::. Types with an optional field show the type label plus a subject chip; the rest show just the label.

Tip

Tip

1. Draw and label a diagram.
2. Write an equation relating the variables.
3. Differentiate implicitly with respect to time.

Note

Note

A neutral aside for context that isn’t a warning or a tip.

Warning

Do not confuse rate-constant units across reaction orders.

On the examLinearized plots

AP often asks you to justify reaction order from a linearized plot.

Key infoFirst-order half-life

First order: $t_{1/2} = \dfrac{0.693}{k}$

Common mistakes

• Using the first-order half-life when the reaction is second order.
• Dropping units on $k$ before comparing trials.

Working checklist

1. Identify the rate law from initial-rate data.
2. Integrate the rate law for concentration vs. time.
3. Check the units on $k$ against the reaction order.

Problem-solving strategy

1. Draw and label a diagram.
2. Write an equation relating the variables.
3. Differentiate implicitly with respect to time, then solve for the unknown rate.

Conditions

1. Random sample or random assignment.
2. Independence: if sampling without replacement, $n \le 0.10N$.
3. Large counts: $n\hat{p} \ge 10$ and $n(1-\hat{p}) \ge 10$.

SummaryRate laws

Rate laws come from a mechanism or from experiment; order is not always equal to the stoichiometric coefficients.

Key equations

Idea	Equation
First-order decay	$\ln[A]_t = \ln[A]_0 - kt$
First-order half-life	$t_{1/2} = \dfrac{0.693}{k}$

Useful variables

• $[A]$ = concentration of reactant $A$ (Units: $\text{mol/L}$)
• $k$ = rate constant (units depend on overall order)
• $t_{1/2}$ = half-life (Units: $\text{s}$)

---

Theorem boxes

Authored as <div class="theorem-box"> with a bold lead-in. Colour-coded by the lead-in word. Leave a blank line after the opening tag and before the closing tag.

Definition. A rate law relates reaction rate to reactant concentrations.

Theorem. For an elementary step, the order in each reactant equals its stoichiometric coefficient.

Examples should use a plain **Example.** lead-in. Make the problem statement end with what the student is trying to find or derive.

Example. Initial-rate data triples the rate when $[A]$ triples. Find the order in $A$.

The rate is first order in $A$, so rate $= k[A]$.

Proofs should name what they are proving in parentheses.

Proof (First-order integrated rate law). Separating variables in $\frac{d[A]}{dt} = -k[A]$ and integrating gives $\ln[A]_t = \ln[A]_0 - kt$.

---

Practice blocks

For normal notes, practice problems can be a numbered list. When you include solutions, put each solution in a theorem box with a ### Solution heading.

## Practice

1. What is the pH of a $$1.0\times10^{-3}\ \text{M}$$ HCl solution?

---

## Solutions

<div class="theorem-box">

### Solution 1

Strong acid means $$[\text{H}^+] = 1.0\times10^{-3}$$, so:

$$
\boxed{\text{pH} = 3}.
$$

</div>

The nested problem/solution block below is also available for richer interactive practice pages.

1. What is the pH of a $1.0\times10^{-3}\ \text{M}$ HCl solution? (A) 3 (B) 11 (C) 7 (D) 1

---

MDX components

Imported at the top of an .mdx page: import { Card, CardGrid, Pills, Callout } from '…/components/mdx'.

• Inline tags
• Topics
• Skills

📘 Linked card

Cards can link somewhere, with a hover lift and a call-to-action.

Browse notes →

🗂️ Plain card

Or just group related content without a link.

✦ MDX vs directive

This <Callout> is the MDX component; the :::tip above is the directive. Use whichever fits — directives in plain .md notes, components in .mdx pages.

---

Math & figures

Inline $E = mc^2$ and display:

$$\int_0^1 x^2\,dx = \frac{1}{3}$$

---

Automated checks

Before committing, run the note checker from astro/:

npm run check:notes

The checker catches the mechanical issues that most often break notes: unclosed math, missing front matter, unbalanced <div> tags, leftover markdown="1", old relative_url image paths, and bare | in math.