Každý diagram Mermaid sestaveného webu dostane id (diagram-<name>), seznam svých uzlů, ovládací prvky prohlížeče a odkaz pro každý uzel, který je identitou objektu, k němuž web má stránku, vše odvozené při buildu; odkaz na

Co to znamená

Diagram na webu je oplocení ```mermaid v dokumentu nebo zdroj Mermaid, který šablona zapisuje z generovaných dat. Po buildu každý z nich:

• má id, diagram-<name>, takže #diagram-<name> na něj dopadne s JavaScriptem i bez něj;
• vypíše uzly, které jeho zdroj deklaruje, v atributu data-nodes;
• má vedle sebe panel nástrojů prohlížeče, zapsaný hidden;
• má vedle sebe odkaz pro každý uzel, jehož id nebo popisek je identitou objektu, pro který tento build napsal stránku: úkol, milník, rozhodnutí, pravidlo, doktrína, příkaz, schopnost, dokument.

Nikdo nic z toho nepíše. Odkaz na jeden uzel, #diagram-<name>:<node>, se při sestavení řeší proti uzlům, které diagram deklaruje, a odkaz na neexistující uzel je nález.

Princip

scripts/site-build spouští scripts/lib/diagrams.mjs nad stránkami, které zapsala Zola, dřív než se přimíchají stránky jiných producentů. Jméno je data-diagram deklarované šablonou, jinak id nadpisu, pod nímž diagram sedí, jinak jeho pořadí na stránce; druhý diagram pod jedním nadpisem je <name>-2. Identity a jejich trasy se čtou z site/data/generated (plan.json, entities.json, commands.json, executable.json, doctrines.json, docs.json) a identita, jejíž stránku sestavení nezapsalo, se nenabízí. Popisek, který pojmenovává dva objekty nebo takový, pro nějž web nemá stránku, nevede ani na jeden.

Odkazy jsou běžný markup, takže o každém z nich rozhoduje scripts/ci/link-check spolu s ostatními odkazy webu. Stejná kontrola čte id a data-nodes, které průchod zapsal pro rozlišení adresy uzlu.

Jak to vidět

node --test scripts/lib/diagrams.test.mjs
bash test/run.sh 3006_diagrams_are_interactive_and_linkable

Případ sestaví vlastní web se třemi diagramy na jedné stránce, spustí průchod a scripts/ci/link-check nad ním a poté zasadí čtyři vady: odkaz na uzel, který diagram nedeklaruje, odkaz na uzel patřící jinému diagramu na téže stránce, odkaz do diagramu, který stránka nenese, a dva diagramy deklarované pod jedním jménem. Každá musí být zamítnuta nálezem, který ji pojmenuje. Případ také vyžaduje, aby úkol, jehož stránka nebyla sestavena, zůstal nenalinkován, aby zdroje diagramů zůstaly beze změny a aby druhý běh nezměnil žádný soubor.

Co nepokrývá

Tvrzení se týká toho, co build zapisuje a o čem rozhoduje link-check. To, že prohlížeč (site/diagrams.js) přibližuje, posouvá a otevírá adresu v browseru, ověřuje spec diagram v scripts/interaction-probe, který potřebuje browser a není součástí tohoto tvrzení.

Uzly se čtou pro vývojové diagramy a stavové diagramy. Jakýkoli jiný druh diagramu je pojmenován a adresovatelný jako celek a nemá odkazy na uzly ani adresy uzlů. Syntaxe Mermaid, kterou parser nečte, stojí chybějící odkaz, ne chybný, kromě případu, kdy popisek náhodou odpovídá identitě, kterou nemá na mysli.

Odkazy zvenčí webu na adresu diagramu nejsou chráněny: přejmenování nadpisu, pod kterým diagram leží, mění jeho adresu.

Proč existuje

Pravidlo project.a-diagram-is-drawn-not-typed přesunulo každý publikovaný vztah do Mermaidu, protože zpracovatelný diagram lze odkazovat a kontrolovat. Do ADR 0152 žádný nic neodkazovalo ani nekontrolovalo: uzel, který byl úkolem nebo příkazem, byl text na webu, který má pro každý stránku, a diagram neměl adresu, na kterou by se dalo odkázat.