Lesson PDFs

Build a document the learner can return to without the conversation. Keep the teaching sequence visible: question, explanation, worked example, changed case. Use headings to mark conceptual changes rather than decorating every paragraph.

Run the commands below with the project's .venv/bin/python when that environment is present. Check that interpreter before treating a missing package in the system Python as a missing PDF capability. For a fresh environment, install skills/pdf/requirements.txt there.

1. Select the lesson's outcome and audience. Read only the necessary teacher and subject context. Do not print internal learner records or hidden assessment criteria in a handout unless requested.
2. Write the lesson as Markdown or use an existing README. Place diagrams and image-model outputs beside it and reference them with ![caption](image.png). HTML <img src="..." alt="..."> works too. Keep captions and source credits.
3. Convert with python3 skills/pdf/scripts/markdown_to_pdf.py lesson.md -o output/lesson.pdf. This also writes editable lesson JSON. Dependencies: ReportLab, Pillow, markdown-it-py; Matplotlib supplies fonts and equation rendering. Fenced math blocks render as equations. Remote images become explicit source links; save a permitted local image first when the figure must appear in the PDF. For precise block control, use build_pdf.py lesson.json -o output/lesson.pdf; see references/lesson-format.md.
4. Render pages with pdftoppm -scale-to 1400 -png output/lesson.pdf output/lesson. Inspect every page. Check equations, captions, page breaks, text size, and source links; extraction alone cannot establish visual quality.
5. Extract text with pdftotext or pypdf and check for omissions or missing glyphs. Deliver the PDF with its editable source. State any unverified layout.

Register the artifact

The viewer page shows the topic's pdf chip as ready only after the PDF is registered. Copy it into the course workspace, then register:

cp output/lesson.pdf learners/<learner>/courses/<course-id>/artifacts/documents/<slug>.pdf
python3 skills/course-design/scripts/manage_artifact.py --learners-root learners \
  register <learner-id> <course-id> --file artifact.json

Use type: document, mime_type: application/pdf, the topic's lesson_id, and status: ready. Then re-render the page:

python3 skills/course-viewer/scripts/render_viewer.py learners/<learner>/courses/<course-id>

Typography and figures

Use a calm hierarchy: serif body, sans heading, mono code; 11–12 pt body with comfortable leading and margins. The builder embeds DejaVu fonts when found; use --font-dir for another installation of that family. It fails if the font set is incomplete rather than silently substituting missing glyphs.

Keep diagrams labeled and interpretable without color alone. Preserve image aspect ratio; avoid enlarging a tiny raster into a blurry page. Keep the caption with the figure. Include source/creator and whether a diagram is schematic. Use actual math rendering for equations; do not send raw LaTeX to paragraph text.

Read references/visual-review.md when inspecting. examples/lessons/gradient/README.md exercises the builder with equations, an image, a comparison table, and a worked example.