Side annotations on a page without a table of contents

This page shows side annotations on a page that has no table of contents. The text stays in Starlight’s content column. A side annotation block with lines too long for that column spreads over the free space on each side. Then it shows the notes beside the code. Make the window narrower to see the notes move under the block.

This block needs a width of 800 px:

orders.py

import csv
from collections import Counter
from pathlib import Path


def load_orders(path: Path) -> list[dict[str, str]]:
    with path.open(newline="", encoding="utf-8") as fh:1
        return [r for r in csv.DictReader(fh) if r["status"]]2


def count_by_status(orders: list[dict[str, str]]) -> Counter[str]:
    return Counter(order["status"] for order in orders)3

1. 1Note 1, for line 7: newline="" lets the CSV reader handle line ends.
2. 2Note 2, for line 8: Skips rows with no status.
3. 3Note 3, for line 12: Counts the orders for each status.

This block needs a width of 1000 px:

report.py

from pathlib import Path

from orders import count_by_status


def write_report(orders: list[dict[str, str]], out: Path, *, width: int = 12):1
    counts = count_by_status(orders)
    items = sorted(counts.items(), key=lambda item: item[1], reverse=True)2
    out.write_text("\n".join(f"{status:<{width}} {n:>6}" for status, n in items))3

1. 1Note 1, for line 6: * makes width a keyword argument.
2. 2Note 2, for line 8: The largest counts come first.
3. 3Note 3, for line 9: One line for each status, in columns.

The lines of this block fit the content column, so the block stays in line with the text:

main.py

import sys
from pathlib import Path

from orders import load_orders
from report import write_report

orders = load_orders(Path(sys.argv[1]))1
write_report(orders, Path("report.txt"))

1. 1Note 1, for line 7: Reads the file from the command line.