{% set page_title = 'Links' %}
{% include '_header.html' %}
{#- The shared toolbox (ADR-0030). Not documentation and not a runbook — a
subject's runbook lives on the check that watches it — but the two or three
dashboards and tools somebody mid-incident wants *now*, without hunting
through a wiki. So: a launcher. One flat level of groups flowed into columns,
each entry a mark and a title, curated order preserved exactly as written.
Everything on it comes from the deployment's own `config/links.yaml`; this
file owns only how it looks. -#}
{%- macro icon_mark(link) -%}
{#- A brand logo does not theme: a black mark vanishes on the dark themes and
a white one on the light. So an icon that declared a **pair** emits both
files and CSS hides one — the choice cannot be made here, because under
the `auto` theme the server does not know what the OS will resolve to.
Anything else — one file, a favicon — rides a **theme-invariant light
chip**, which is what keeps a single-file mark legible in every theme, and
one image serves both backgrounds: a second would be the same bytes fetched
twice. The chip is the floor, the pair is the upgrade (ADR-0030 §4).
Which images, and where each is from, is `LinksConfig.mark_for`'s answer,
because the page's own Content-Security-Policy is taken from the same one:
an image with a `url` is fetched from elsewhere — a remote mark, or the
entry's site favicon — and one without is ours, by the entry's name. -#}
{%- set mark = links_config.mark_for(link) -%}
{%- for image in mark.images -%}
{%- endfor -%}
{%- endmacro -%}
{#- The setup guide, folded (ADR-0030). With no links the page used to be the
guide in full — a sample file, where it goes, the roster of installed marks,
how to add one — more than a screen before anybody had a link; and a
deployment that had written its file lost the roster with the empty state. So
the guide is two folds, each the browser's own disclosure and closed, which
works without script: *Add links* on a page that has none, and *Icon names*
there and at the foot of a page that has links.
A fold is a card, whose surface Bootstrap paints. What its summary adds beside
its name is muted from our own token for that reason: `.text-muted` is an ink
nobody here measured on that surface (`tests/test_contrast.py`). -#}
{%- macro fold(name, aside) -%}
{{ name }}· {{ aside }}
{{ caller() }}
{%- endmacro -%}
{#- The roster and how a deployment adds a mark of its own. It stands alone under
a page that has links, so it names the file it means rather than pointing at a
fold that is not there. -#}
{%- macro icon_names_fold(icon_names) -%}
{%- call fold('Icon names', (icon_names | length) ~ ' installed, and how to add your own') %}
{%- if icon_names %}
icon: takes a name, never a URL — a
dozen entries for one tool cost one mark, one fetch, one
probe. These names are already installed. Each is drawn
twice, once for a light background and once for a dark
one, and the page picks by theme:
{#- The whole roster, not an example of one: the reader is choosing a
name, and a name they cannot see is one they will write wrong. The
list is the **registry** (built-in pack plus anything a dependent
package registered), so every row here is servable by the icon
route — the deployment's own map is not in it, since an entry
there may be a remote URL or a suppression, neither of which has
bytes to serve. The images are decorative: the name they belong to
is the row header beside them, so `alt` is empty rather than a
second reading of it. A file that fails to load still becomes the
neutral glyph — links.js delegates on `.ls-links__mark`, which is
why each one keeps that wrapper here too. -#}
name
on light
on dark
{%- for name in icon_names %}
{{ name }}
{%- for variant, side in (('on-light', 'light'), ('on-dark', 'dark')) %}
{%- endfor %}
{%- endfor %}
{%- endif %}
To use a mark of your own, put an icons/
directory beside links.yaml and drop the file
in: firewall.svg is the name
firewall. Name it after one of the installed
marks and it replaces that one. A pair —
firewall-on-light.svg and
firewall-on-dark.svg — is one name with a
drawing for each background; a single file rides a light
chip instead, so it stays legible under every theme.
{%- endcall %}
{%- endmacro -%}
Links
{%- if links_config.problems or probe.icon_failures %}
{#- The audience for these is whoever maintains the file, and that person
is looking at this page, not at a service log. The structural ones are
logged too, and none of them stopped the page from loading. A remote
icon that stopped answering joins them: an icon is not a row on this
page, so its verdict has nowhere to sit beside — and a mark that rotted
is a problem with this file exactly as a misspelled key is. -#}
Problems in this deployment's link configuration
{%- for problem in links_config.problems %}
{{ problem }}
{%- endfor %}
{%- for failure in probe.icon_failures %}
the icon named {{ failure.name }} did not answer:
{{ failure.verdict.detail }} ({{ failure.verdict.url }},
checked {{ failure.verdict.checked_at | since }})
{%- endfor %}
{%- endif %}
{%- if links_config.is_empty() %}
{#- The empty state keeps the page and its nav entry and says what the page
is: an empty toolbox is a deployment that has not filled it in yet, not
a broken install. One sentence, for every reader alike — the page knows
no roles — and the guide a step away, in its two folds. -#}
No links yet. This page is the deployment's toolbox,
the dashboards and tools to have at hand in an incident, and it has
not been filled in.
{%- call fold('Add links', "one file in this deployment's configuration") %}
Links come from this deployment's own configuration — one
flat level of groups, each with an ordered list of entries:
Put that in {{ links_file }} and reload — the
file is re-read when it changes, so nothing needs
restarting.
{%- endcall %}
{{ icon_names_fold(icon_names) }}
{%- else %}
{#- The filter is the primary navigation once a page reaches sixty
entries, not a nicety — so it is pinned above everything, focused on
arrival, and costs no round trip. It matches **titles** (ADR-0030);
what the server puts in `data-ls-match` below is the whole of what it
searches: the entry's title **and its group's**, so typing a category
name pulls up that whole category. Notes stay out — a note is prose,
and a match the reader cannot see in the title it landed on is the
failure mode records were chosen to avoid. -#}
{#- Announced politely rather than shouted: it changes on every
keystroke, and it is a reassurance, not an event. -#}
{#- One freshness line for the whole page, and only where a deployment
asked for probing at all: a `check:` block that switches everything
off must not leave a permanent "nothing checked yet" for a question
nobody asked. Sixty healthy rows stay undecorated — only a failure
is drawn beside its entry — so without this line a reader could not
tell a clean page from an unprobed one. The age is the newest answer
the page holds; a verdict older than that carries its own beside the
entry it belongs to. -#}
{%- if probe.active %}
{#- **Green when every answer came back alive**, and only then. A page
whose failures are all drawn in red rows still needs to say that the
clean ones were actually asked — and a reader mid-incident reads a
color before a sentence. Anything failing leaves the line muted
rather than turning it red: the failing rows already carry that, and
a second red would compete with them. The tick is drawn here in
`currentColor`, like every other mark this project draws itself. -#}
{%- set all_alive = probe.checked_at and not probe.failures %}
{%- if all_alive %}
{%- endif %}
{%- if probe.checked_at %} Checked {{ probe.checked_at | since }}
{%- else %}Nothing checked yet{% endif -%}
{#- A pass still in flight as this response was built — after a
*check now* that reached its deadline, or beside an open that
started one. The page does not poll, so saying so is the
difference between a control that looks broken and one whose
remaining answers are one reload away. -#}
{%- if probe.running %} · still checking{% endif -%}
{#- A pass that reached its deadline and walked away from a host
still holding the connection open (ADR-0030). Said
here rather than only in the log, because this is the one
condition under which the age beside it stops meaning what it
says: without this line, somebody pressing *check now* and
watching nothing move would conclude the button is broken
rather than that a target is refusing to answer. The plural
form is the apology — at that point nothing is being probed at
all until one of them lets go. -#}
{%- if probe.paused %} · paused — {{ probe.stuck }} earlier passes are still waiting on a host that has not answered
{%- elif probe.stuck %} · {{ probe.stuck }} earlier pass{{ 'es are' if probe.stuck != 1 else ' is' }} still waiting on a host that has not answered
{%- endif -%}
{#- *Check now*, because the time gate is exactly wrong in the one moment
somebody has just fixed a URL and wants to watch it go green. A form
POST answered with a redirect, like every other control here that
changes something: a GET would let a reload or a prefetch spend
outbound requests, and the redirect is what stops a refresh from
firing a second pass. It sits at the far end of the row, away from
the search box — this page is read mid-incident and the filter is
its primary navigation, so the one control that costs something must
not be reachable by a stray keystroke while typing. -#}
{%- endif %}
Nothing matches. Esc clears the filter.
{%- for group in links_config.groups %}{% if group.links %}
{{ group.title }}
{%- for link in group.links %}
{#- What the filter searches, lower-cased server-side so the
client compares strings and nothing else. The group's title
rides along on every entry: an operator who types the
category means the category. -#}
{#- The icon names, at the foot and closed: whoever adds a fortieth link
reads a name here rather than guessing one, and a page that is read
mid-incident carries one line for it, under everything that is on
fire. Outside the columns, so the filter never hides it. -#}
{{ icon_names_fold(icon_names) }}
{%- endif %}
{#- The last step of the search path. An icon that fails to load is replaced by
this, so the page never shows a browser's broken-image glyph — the failure
the reference implementation was showing three of. It is a template rather
than an `onerror` attribute because links.js wires the swap: an inline
handler would be the one reason a Content-Security-Policy could not be turned
on later. It draws in `currentColor`, so it needs neither a chip nor a pair. -#}
{% include '_page_end.html' %}