Plotting in docs

Altair plots

Use Altair for plots in QMD documents and give every figure a Quarto label and caption. Figure labels should use the fig- prefix. Normally AI can do those Altair figures fine, with the slight modification of the plot being includable in the Quarto generated HTML document.

For larger plots preffer rendering into svg or png to not make the rendered page resource heavy.

import altair as alt

plot_df = alt.Data(
    values=[
        {"x": 1, "y": 2, "category": "A"},
        {"x": 2, "y": 4, "category": "A"},
        {"x": 3, "y": 3, "category": "A"},
        {"x": 1, "y": 3, "category": "B"},
        {"x": 2, "y": 5, "category": "B"},
        {"x": 3, "y": 6, "category": "B"},
    ]
)

chart = (
    alt.Chart(plot_df)
    .mark_line(size=2)
    .encode(
        x=alt.X("x:Q", title="X label [unit]"),
        y=alt.Y("y:Q", title="Y label [unit]"),
        color=alt.Color(
            "category:N",
            title="Category",
            legend=alt.Legend(
                orient="top",  # important!
                direction="horizontal",
                columns=6,
                symbolSize=90,  # important!
                labelFontSize=13,  # important!
            ),
        ),
    )
    .properties(
        width=850,  # important!
        height=400,
    )
)

chart

Figure 1: Short descriptive caption

Keep legends above the plot, horizontal, and easy to read. Use a plot width of 850 to fit the content width.