Components and visual identity¶

Cover¶

deck.cover accepts a title, description, tags, section summaries and an optional animated terminal card. Line breaks in plain descriptions use \n. Omit hero_code and hero_result for a text-only cover. footer_label separates the short footer label from the lesson name.

Two cover sections preserve the original two-column layout. Other section counts adapt automatically. Colors and fonts come from the library, so authors do not need to write HTML or CSS for ordinary lessons.

Slide and cards¶

deck.slide groups a concept into a title, explanation and cards. A card can contain title, explanation, code, reason and language. Empty reasons do not create an empty panel. Use a small example that isolates the concept; put longer exercises in executable notebook cells.

Code is displayed left-to-right with whitespace preserved. Python highlighting is built in. Other languages use optional Pygments; unavailable or unknown lexers fall back to escaped plain text.

Concept diagrams¶

Diagrams work for any subject:

deck.slide("From evidence to a conclusion", diagram={
    "title": "Reasoning process",
    "direction": "ltr",
    "nodes": [
        {"value": "Question", "note": "Define the problem"},
        {"value": "Evidence", "note": "Observe"},
        {"value": "Conclusion", "note": "Explain", "selected": True},
    ],
    "caption": "Check each connection before moving on.",
})

Diagram direction is independent of lecture direction. Use arrows=False for a comparison instead of a flow. The optional Python presets are journey, names, cast, arithmetic, index, decision, loop, list, collections, function and error.

Close and reopen the diagram disclosure to replay its reveal animation. No application JavaScript is required for these interactions.

Reveal activities¶

activity requires question and answer. Optional code, language, label and reveal customize the task and button text. The answer starts collapsed and can be opened with a keyboard.

The answer is present in HTML source. Use reveal activities for formative learning rather than hiding confidential exam solutions.

Notes and tables¶

deck.note("Remember", "State the assumption.\nTest a boundary case.")
deck.table("Comparison", ["Structure", "Use"], [["list", "Ordered values"], ["dict", "Named fields"]])

Every table row must match the number of headers. Wide tables and code blocks can scroll inside their containers.

Theme settings¶

Option	Default	Meaning
`preset` / `theme`	`gold`	`gold`, `emerald` or `ocean`
`accent`	`None`	Custom `#RRGGBB` accent
`background`	`None`	Custom `#RRGGBB` background
`direction`	`rtl`	`rtl` or `ltr`
`motion`	`True`	Enable component animation and transitions
`max_width`	`1280`	Maximum component width, 320–2400 pixels
`notebook_style`	`False`	Opt in to JupyterLab notebook canvas styling
`external_fonts`	`False`	Use remote Google Fonts instead of bundled fonts

Gold without custom colors preserves the original typography, gradients and component spacing. Each deck has a unique CSS scope so multiple course themes can coexist. Notebook canvas styling is explicitly opt-in and applies to surrounding cells in that notebook.

Reduced-motion system preferences disable animation. motion=False also disables it explicitly. Print styles stop motion; expand reveal answers before printing if they should appear in the handout.

Plain text and trusted HTML¶

Plain strings are escaped by default. To supply HTML authored and trusted by you:

from jupyter_lecture_studio import RichText

deck.slide("Slicing", RichText("Use <code>start:stop:step</code>; the end is excluded."))

RichText is an explicit trust boundary, not an HTML sanitizer. JSON course files use plain strings.