Zdůvodnění
Navigace vypadá jako prezentace a není. Je to tvrzení o tom, k čemu tento projekt slouží — hrstka otázek, s nimiž návštěvník přichází, a stránky, které na ně odpovídají — a vykresluje se nejméně na třech místech každé stránky webu. To z ní dělá přesně ten druh faktu, na který tento repozitář dává pozor: uvedený jednou, promítaný mnohokrát a bezcenný ve chvíli, kdy ho začne uvádět i projekce.
Změřila to dvě selhání a obě byla neviditelná, dokud platila.
První je deklarace, která lhala o tom, že je deklarací. site/data/nav.toml nesl hlavičku, že se z něj vykresluje patička. Patička nav vůbec nečetla: bylo to pět odkazů napsaných ručně, takže web měl dvě navigace a tu druhou nešlo změnit úpravou souboru, který se hlásil, že ji vlastní. Soubor, který se vyhlašuje za jediný zdroj, je nebezpečnější než ten, který ne, protože čtenář, který mu věří, přestane hledat — tvar, který pojmenovává project.derived-once, v kostýmu opravy.
Druhým je táž trasa deklarovaná dvakrát pod dvěma jmény. /docs/cli/ a /docs/api/ se objevily ve dvou skupinách, v každé označené jinak, protože kategorie, pod nimiž seděly — Executable a Reference — odpovídaly na stejnou otázku. Návštěvník potkal stejnou stránku dvakrát a musel hádat, který štítek je ten pravý, což je informační architektura, která svou práci předává čtenáři. Přežilo to proto, že nic neporovnávalo soubor sám se sebou. Ta verze souboru nesla devět skupin nejvyšší úrovně; duplicita nebyla jejich shodou okolností, byla důsledkem: kategorie se množí, dokud dvě neznamenají totéž, a pak se jejich obsah překrývá.
Požadované chování
site/data/nav.toml je jediná deklarace. Uvádí [[groups]], items každého z nich a jediné [cta]. Nic jiného je neuvádí a nic nevyjmenovává trasu, kterou vlastní generátor — funkce, modul, schopnost nebo stránka příkazu se dosáhne přes svůj index, nikdy se zde ručně nevypisuje.
Žádný href se v něm neobjeví dvakrát. Ani napříč skupinami, ani v rámci jedné. Existuje právě jedna výjimka a je to rozhodnutí o vykreslení, ne druhá položka: vlastní href skupiny se může opakovat jako href její první položky, což je přistávací odkaz rozbalovací nabídky — stránka, na kterou se dostanete kliknutím na samotnou skupinu. Táž trasa pod druhým popiskem kdekoli jinde je výše uvedená vada.
Hlavní navigace zůstává malá: nejvýše šest skupin. Navigační lišta není mapa webu. Ne každá stránka si v ní zaslouží místo a kategorie, která existuje proto, že stránka potřebovala domov, je začátek duplikace, o které toto pravidlo je.
Každá projekce se odvozuje. Šablona, která vykresluje navigaci webu, čte nav.groups; vedle toho nepíše cesty. To dnes pokrývá site/templates/partials/navbar.html a site/templates/partials/footer.html i každý povrch, který je spojuje. Dva doslovné tvary se počítají jako psaní cesty — href="/docs/" a get_url(path="/docs/") — a dvě věci jsou vyňaty deklarací: odkaz domů /, který nese každá stránka a nikdy žádná skupina, a cokoli, co už nese sama deklarace, k čemuž deklarace slouží. Cesta sestavená z proměnné je výpočet, ne psaná cesta, a externí URL nikdy nezačíná /.
Výzva k akci existuje a rozřeší se. Je to akce, a ne šestá kategorie, a je to jediný odkaz na liště, který nesmí být mrtvý.
Chování při selhání
scripts/ci/nav-check, registrovaná jako kontrola nav-check na třídě cest site, selže s exit 10 a pojmenuje každý nález: dvě místa, kde byl zapsán duplicitní href, počet skupin proti limitu, šablonu a routu, kterou typovala, šablonu, která vykresluje navigaci bez čtení nav.groups, a výzvu k akci, na kterou žádná stránka neodpovídá. Chybějící nebo neparsovatelný site/data/nav.toml je exit 12 — nepoužitelný, nikoli čistý, protože kontrola, která nedosáhne svého předmětu, to musí říct, místo aby prošla.
Náprava míří vždy stejným směrem: přesunout fakt do deklarace a vykreslit ho. Nikdy naopak.
Ověření
scripts/ci/nav-check # the gate
bash test/run.sh 273_navigation_is_declared_oncetest/cases/273_navigation_is_declared_once.sh staví fixture web pro každý tvar, který musí kontrola rozlišit — čistou navigaci, jejíž skupiny legitimně opakují svůj href jako první položku, trasu deklarovanou ve dvou skupinách, trasu deklarovanou dvakrát v jedné skupině, sedm skupin, výzvu k akci mířící na žádnou stránku, šablonu, která trasu zapisuje, a šablonu, která tutéž trasu řeší přes get_url, šablonu, která vykresluje navigaci bez čtení deklarace, a deklaraci, která chybí nebo je poškozená — takže se kontrola měří tím, o čem rozhoduje, ne tím, co tento repozitář náhodou obsahuje. Poslední aserce případu pouští kontrolu proti samotnému tomuto repozitáři.