monarch-initiative/mechmaker/site-design

Site design

Most changes are one line in conf/site.yaml. Start there. Edit the page templates only for what the settings cannot do.

Settings: conf/site.yaml

The names are Material for MkDocs' own, so one name colors both sites.

After any change:

just site-check     # validates the file and reports contrast
just docs-serve     # look at both sites at http://127.0.0.1:8000

Choosing colors

• Pick for the domain, not for decoration. A palette the maintainers

already use (a lab or project color) is a good choice.

• Readability is handled for links: the browser darkens or lightens the

palette color until it reaches 4.5:1 against the page, and picks black or white header text, whichever reads better. just site-check shows the final colors. The docs site uses Material's own pairings, which for a few light palettes (cyan, light-green, and similar) put white text under 3:1 on the header; prefer a darker palette if the docs header must be readable.

• Ask the person before changing an established color. It is part of how

people recognize the site.

Maps

A record page draws a map when the record holds a place, at any depth. The schema says what is a place, not the keys (src/datmech/shapes.py):

All are in decimal degrees (WGS84). Each is named after what holds it (its name or preferred term, else the section) and colored by its section; a list beside the map turns each off. A line or area too small to see at the starting zoom gets a dot at its center. just validate rejects a shape with a part missing or out of range, south north of north, or WKT that does not parse; a box whose west is east of its east crosses the antimeridian.

If the person wants a map and the records have no places yet, the schema needs them: mechmaker's add-record-map skill says which shape to use, the classes to add, where coordinates can come from, and how to quote them. Maps are on by default; map: false in conf/site.yaml turns them off.

The map is drawn in record.html. Its colors are a fixed set chosen to be told apart by color-blind readers, and the layer list keeps dark text, since Leaflet draws it on white in both themes. OpenStreetMap's tile policy asks for the attribution the map shows and for light use; a site with heavy traffic should use its own tile server.

Beyond the settings

A record page is laid out from the shape of the data and the schema, by src/datmech/render.py. Its docstring lists the rules: an overview table for simple values, tables for lists of small uniform objects, cards for curated mentions and richer objects, quote cards for evidence.

Field labels come from the schema. To rename one on the page, give the slot a title in the schema; do not special-case it in a template. Its description is the help text under the section heading, so a thin page is fixed by improving the schema.

The page frames are Jinja templates in src/datmech/templates/:

To change how a kind of value is drawn (say, show a list as cards rather than a table), change the rule in render.py and keep its docstring true.

Rules:

• Keep colors in conf/site.yaml. In style.css, use the var(--...)

names, never a new literal color.

• Keep every link relative. The site is hosted under a path, and the

record browser sits inside the docs site at /records/.

• After editing a template or render.py, look at the result with

just docs-serve at desktop and phone widths. pages/ is not committed; the docs build renders the browser fresh.

The docs site's layout is mkdocs.yml; its pages are docs/. Never edit .mkdocs.site.yml, site/, or docs/records/: they are generated.

If a request needs a setting that does not exist yet (a logo, a second table layout), add it to conf/site.yaml, read it in site.py and the templates, document it in this skill, and say so in the pull request.