Użyj zagnieżdżonych podgrafów schematu blokowego dla kontenerów z tytułami, także bloków liściowych. Jeśli puste kontenery renderują się nieprawidłowo, dodaj niewidoczny element wypełniający wewnątrz każdego liścia. Pozwoli to zachować widoczną hierarchię; sprawdź wynik w zainstalowanej wersji renderera Obsidiana.

W tym poradniku utworzymy jeden neutralny diagram: zewnętrzny blok o tytule Collection, zawierający Group A i Group B, a w każdej grupie — liściowe kontenery z tytułami. Celem jest zachowanie wyglądu liści jako kontenerów z nagłówkami, zamiast zastępowania ich zwykłymi prostokątami z etykietami.

Co powinno reprezentować liściowy blok z tytułem?

Każdy widoczny kontener przedstaw jako subgraph, niezależnie od tego, czy zawiera inny znaczący blok. Mermaid opisuje podgrafy, jawne identyfikatory podgrafów i zagnieżdżanie w przykładach schematów blokowych. Zwykła deklaracja węzła, taka jak leafA["Block A"], tworzy węzeł z etykietą; nie deklaruje kontenera z tytułem. Zobacz Schematy blokowe — podstawowa składnia.

W tym przykładzie odróżnij widoczny model od elementów pomocniczych układu. Collection, grupy i bloki liściowe to znaczące elementy. Element wypełniający jest szczegółem implementacyjnym, który zapewnia zawartość kontenera liściowego na potrzeby układu. Dodanie tego elementu pomocniczego nie zmienia deklaracji liścia z podgrafu na węzeł.

To rozróżnienie wyznacza też granice tego podejścia: powstaje diagram, którego widoczne liście pozostają kontenerami z tytułami, ale jego źródło zawiera zwykłe węzły pomocnicze. Jeśli wymaganie zabrania deklarowania jakichkolwiek węzłów, także niewidocznych elementów pomocniczych, to obejście go nie spełnia.

Sprawdź, którego renderera używa instalacja na Macu

W Obsidianie otwórz Settings na pasku bocznym, a następnie wybierz General i zanotuj wersję aplikacji. Dokumentacja ustawień Obsidiana wskazuje, że informacje o wersji znajdują się w sekcji General. Przy wyborze odpowiednich informacji o wydaniu uwzględnij tę wersję.

Istnieje istotna różnica między rendererami. Oficjalne informacje o wydaniu z 22 października 2026 r. określają wersję Desktop 1.15.0 jako wczesny dostęp i podają, że renderuje ona składnię Mermaid za pomocą biblioteki Pele Obsidiana, zapewniając zgodność ze składnią Mermaid 12.1.0. W tym samym wydaniu klasy generowane dla diagramów zmieniono na klasy Pele. Nie zakładaj, że starsza instalacja używa Pele ani że zgodność oznacza identyczny wynik jak w Mermaid.js. Zobacz Obsidian 1.15.0 Desktop (wczesny dostęp).

Dokumentacja Mermaid pobrana na potrzeby tego poradnika wyświetla wersję 12.2.0. To inna wersja niż poziom zgodności wskazany w informacjach o wydaniu Obsidiana. Traktuj dokumentację, edytor online i zainstalowaną aplikację jako osobne środowiska, dopóki nie sprawdzisz tego samego przykładu w każdym z nich.

Na początek nie dodawaj do diagramu konfiguracji specyficznej dla renderera ani zewnętrznych selektorów arkusza stylów. Poniższy przykład wykorzystuje podgrafy i style przypisane lokalnie do diagramu, dzięki czemu stanowi niewielki punkt wyjścia do sprawdzenia własnej instalacji.

Utwórz zagnieżdżone kontenery w notatce Obsidiana

Otwórz notatkę w widoku edycji i wklej cały poniższy blok wraz z początkowym i końcowym znacznikiem bloku kodu. Obsidian opisuje diagramy Mermaid jako bloki kodu z potrójnym znakiem akcentu wstecznego i identyfikatorem języka mermaid. W przypadku tego udokumentowanego formatu notatki nie jest potrzebna dodatkowa wtyczka do diagramów. Zobacz Zaawansowana składnia formatowania.

```mermaid
flowchart TB
    subgraph collection["Collection"]
        subgraph groupA["Group A"]
            subgraph blockA["Block A"]
                spacerA[" "]
            end
            subgraph blockB["Block B"]
                spacerB[" "]
            end
        end
        subgraph groupB["Group B"]
            subgraph blockC["Block C"]
                spacerC[" "]
            end
        end
    end

    classDef spacer fill:transparent,stroke:transparent,color:transparent;
    class spacerA,spacerB,spacerC spacer;
```

Naciśnij Cmd+E, aby przełączać się między edycją a Reading view. W widoku do czytania obejrzysz gotowy diagram bez kursora edycji odsłaniającego jego źródło. Te skróty opisano w sekcji Widoki i tryb edycji dokumentacji Obsidiana.

Oczekiwany wynik zawiera sześć widocznych kontenerów z tytułami: jedną kolekcję, dwie grupy i trzy bloki liściowe. Każdy liść zawiera element pomocniczy, którego etykieta składa się z pojedynczej spacji. Klasa spacer ustawia przezroczyste wypełnienie, obramowanie i tekst. Łączy to udokumentowany mechanizm klas Mermaid z obejściem dotyczącym układu; Mermaid opisuje classDef i przypisywanie klas w dokumencie o stylach schematów blokowych.

Przykład sprawdzono pod kątem zgodności z udokumentowaną składnią; na potrzeby tego artykułu nie renderowano go w Obsidianie na Macu. Kryterium akceptacji jest więc wizualne i zależy od lokalnego środowiska: powinno być widocznych wszystkich sześć tytułów, każda grupa powinna zawierać przypisane jej liście, a żaden prostokąt elementu wypełniającego nie powinien być widoczny. Dokładne odstępy i położenie elementów względem siebie nie są kryteriami akceptacji.

Zmieniaj etykiety bez modyfikowania hierarchii

Zacznij od zmiany samych tytułów ujętych w cudzysłowy. Pozostaw collection, groupA, blockA i pozostałe identyfikatory unikatowe. Ułatwi to porównanie zmodyfikowanej wersji z przykładem początkowym.

Aby dodać kolejny liść, skopiuj cały podgraf liściowy, nadaj jego podgrafowi i elementowi wypełniającemu nowe identyfikatory, a nowy identyfikator elementu wypełniającego dodaj do końcowego przypisania klasy. Umieść go przed instrukcją end zamykającą grupę. Na przykład czwarty liść w Group B umieść obok blockC, wewnątrz groupB.

Czytaj instrukcje zamykające od środka na zewnątrz: zamknij liść, następnie jego grupę, a potem kolekcję. Wcięcia pomagają dostrzec tę strukturę podczas edycji, ale to położenie każdej instrukcji end decyduje o poprawności źródła.

Dlaczego używać elementów wypełniających zamiast pustych podgrafów?

Zachowanie pustych kontenerów różniło się w zależności od renderera i wersji. W zgłoszeniu Mermaid 5402 opisano pusty podgraf, który nie działał z ELK w Mermaid 10.8.0, podczas gdy dołączony przykład z Dagre działał. To historyczna relacja dotycząca konkretnej konfiguracji, a nie dowód na to, że każdy obecny renderer odrzuca puste podgrafy. Zobacz Renderer Elk nie działa dla pustego podgrafu.

W praktyce warto unikać uzależniania diagramu przeznaczonego dla nieokreślonej instalacji od zachowania pustych kontenerów. Podejście z elementem wypełniającym zapewnia każdemu liściowi jawną zawartość, a znaczący tytuł pozostaje przypisany do podgrafu.

Przy wyborze wymaganej ścisłości źródła skorzystaj z poniższej tabeli:

Wymaganie Podejście początkowe Co sprawdzić
Widoczne liście muszą pozostać kontenerami z tytułami Zagnieżdżone podgrafy z przezroczystymi elementami wypełniającymi Tytuły, zawieranie i ukryte elementy pomocnicze
Źródło nie może zawierać węzłów pomocniczych Wypróbuj puste podgrafy liściowe w docelowym rendererze Czy każdy pusty liść renderuje się poprawnie
Bloki liściowe będą później zawierać rzeczywiste elementy Zachowaj podgrafy liściowe i zastąp ich elementy wypełniające Usuń tylko te elementy pomocnicze, które nie są już potrzebne
Bloki wymagają precyzyjnego rozmieszczenia w kolumnach Osobno oceń diagramy blokowe Mermaid Obsługę składni w zainstalowanej wersji i sposób prezentacji tytułów

Dokumentacja Mermaid poświęcona diagramom blokowym opisuje bloki złożone, kolumny i jawne odstępy. Warto ocenić te funkcje, gdy głównym zadaniem jest rozmieszczenie elementów. Same w sobie nie dowodzą jednak, że konwersja zachowa dokładnie ten sposób prezentacji kontenerów z tytułami. Zobacz Dokumentację diagramów blokowych.

Diagnozowanie nieprawidłowego wyniku

Zmieniaj jedną rzecz naraz. Zachowaj kompletny przykład początkowy w osobnej notatce, aby odróżnić różnicę między rendererami od błędu podczas edycji.

  1. Notatka wyświetla kod zamiast diagramu. Sprawdź, czy początkowy znacznik bloku to mermaid, a następnie przełącz się na Reading view. Porównaj znacznik z udokumentowanym formatem diagramów Obsidiana.
  2. Liść wygląda jak zwykły prostokąt z etykietą. Sprawdź jego deklarację. Powinna zaczynać się od subgraph, a jego element wypełniający powinien znajdować się w osobnym wierszu wewnątrz podgrafu.
  3. Wewnątrz liścia nadal widać mały prostokąt. Sprawdź, czy identyfikator elementu wypełniającego zgadza się z końcową instrukcją class. Tymczasowo usuń stylowanie, aby ustalić, który element pomocniczy widzisz, a następnie je przywróć.
  4. Blok pojawia się w niewłaściwej grupie. Zanim zmienisz ustawienia układu, sprawdź kolejność zamykających instrukcji end.
  5. Diagram działa online, ale w Obsidianie wygląda inaczej. Porównaj informacje o wydaniu zainstalowanej aplikacji z wersją renderera online. Zachowaj działający lokalny przykład jako wzorzec.

Najpierw zachowaj strukturę zawierania, potem koryguj położenie

Gdy tytuły i struktura zawierania są już poprawne, zdecyduj, czy układ jest wystarczająco czytelny. Nie zastępuj podgrafu liściowego węzłem tylko po to, by zmniejszyć jego prostokąt: taka zmiana narusza reprezentację, którą chcesz zachować.

Podobnie dodawaj połączenia tylko wtedy, gdy diagram ma przedstawiać relację wykraczającą poza zawieranie. Mermaid opisuje ograniczenie dotyczące kierunku: połączenie węzła z wnętrza podgrafu z elementem zewnętrznym sprawia, że podgraf dziedziczy kierunek swojego elementu nadrzędnego. Po dodaniu takich krawędzi ponownie sprawdź układ. Zobacz Kierunek w podgrafach.

Na koniec obejrzyj notatkę w szerokości, przy której zwykle ją czytasz. Zachowaj wersję, która wyraźnie pokazuje kolekcję, jej grupy i ich liście z tytułami. Przydatny wynik to czytelna hierarchia zawierania, w której bloki liściowe pozostają podgrafami, a wszelkie niewidoczne elementy pomocnicze układu są jasno zidentyfikowane i łatwe do późniejszego usunięcia.

Źródła