YAML front matter: metadane na początku pliku Markdown
YAML front matter
YAML front matter w Markdown: składnia, pola i przykłady | We.Inc
Czym jest YAML front matter, reguły dotyczące ---, pola, które czytają Jekyll, Hugo, Eleventy i Astro, oraz narzędzie, które pokazuje metadane i treść Twojego własnego pliku.
Front matter to blok YAML na samym początku pliku Markdown, otwierany i zamykany linią z trzema myślnikami (---). Generatory stron statycznych odczytują go jako dane strony, takie jak tytuł, data, layout i tagi, a następnie renderują wszystko poniżej linii zamykającej jako treść strony.
Obsługa front matter w czterech popularnych generatorach stron statycznych
Generator
Formaty
Pola, które odczytuje sam
Jekyll
YAML między ---
layout, permalink, published; we wpisach: date, category, categories, tags
Front matter zamienia zwykły plik Markdown w stronę z metadanymi, a jeden źle postawiony myślnik go psuje. Wklej plik do narzędzia, aby zobaczyć dokładnie, gdzie kończą się metadane i zaczyna treść oraz jakie pola najwyższego poziomu zostały znalezione, zanim zaprotestuje Twój build.
Wklej plik Markdown albo edytuj przykładowy wpis.
Narzędzie sprawdza, czy pierwsza linia to --- (YAML) lub +++ (TOML), i szuka pasującej linii zamykającej.
Pokazuje blok front matter, znalezione proste pola najwyższego poziomu oraz treść, która zostanie wyrenderowana.
Jeśli blok nigdy nie zostaje zamknięty, informuje o tym, bo to najczęstsza przyczyna wyświetlania metadanych na stronie jako tekstu.
Przed otwierającym --- nie może być nic, nawet pustej linii czy znacznika BOM, inaczej większość generatorów potraktuje blok jako zwykły tekst.
Ujmuj w cudzysłów tytuły zawierające dwukropek ze spacją, na przykład "Cennik: co się zmieniło", inaczej YAML odczyta je jako zagnieżdżone mapowanie.
Zapisuj daty jako YYYY-MM-DD, aby generatory i biblioteki YAML zgadzały się co do ich znaczenia.
Własne pola trzymaj w jednym spójnym miejscu. Hugo ma na przykład klucz params przeznaczony na Twoje własne wartości.
Najczęściej zadawane pytania
Czym jest front matter w Markdown?
To metadane zapisane na początku pliku Markdown między dwiema liniami ograniczającymi. Sam Markdown go nie definiuje; generatory stron statycznych i narzędzia do treści przyjęły tę konwencję i odczytują go jako dane przed wyrenderowaniem reszty.
Czy front matter musi być w YAML?
YAML to powszechny wybór domyślny, ale nie jedyny. Hugo akceptuje TOML między liniami +++ oraz JSON w nawiasach klamrowych, Eleventy obsługuje ---json i ---js, a Astro przyjmuje również TOML.
Dlaczego moja strona wyświetla front matter jako tekst?
Zwykle coś stoi przed pierwszym ---, brakuje zamykającego --- albo linia otwierająca ma dodatkowe znaki. Narzędzie powyżej od razu wykrywa dwa ostatnie przypadki.
Czy front matter może być pusty?
Tak. W Jekyll pusta para linii --- nadal oznacza plik do przetworzenia, dzięki czemu w plikach CSS lub kanałach renderowane są tagi Liquid bez żadnych metadanych.
Jak odczytać front matter we własnym kodzie?
Podziel plik na ogranicznikach, sparsuj pierwszą część biblioteką YAML, a resztę przekaż do renderera Markdown. Eleventy robi to za pomocą pakietu gray-matter, którego możesz też użyć bezpośrednio w Node.
Reguły ograniczników
Dokumentacja Jekyll mówi to wprost: front matter musi być pierwszą rzeczą w pliku i musi być poprawnym YAML umieszczonym między liniami z trzema myślnikami. Inne generatory stosują ten sam kształt.
Wewnątrz bloku obowiązują zwykłe zasady YAML. Wcinaj spacjami, ujmuj w cudzysłów wartości ze znakami specjalnymi i używaj list dla tagów i kategorii.
Pola, które warto ustawić na każdej stronie
Tytuł i opis obsługują nagłówek strony i fragment w wynikach wyszukiwania w większości motywów. Data porządkuje wpisy, a draft lub published decyduje, czy strona w ogóle zostanie zbudowana.
Wszystko inne zależy od Twoich szablonów. Każde dodane pole staje się danymi, które layout może wyświetlić, na przykład imieniem autora, ścieżką do głównego obrazu czy czasem czytania.
Przykłady front matter
Wpis na blogu (YAML)
Typowy wpis: tytuł w cudzysłowie, bo zawiera dwukropek, data, lista tagów i własne pole author.
Ten sam wpis z front matter w TOML (Hugo)
Hugo odczytuje +++ jako front matter w TOML. Własne wartości znajdują się pod kluczem params.
Rozdzielacz front matter
Wklej plik Markdown. Narzędzie znajdzie blok front matter, wypisze jego proste pola najwyższego poziomu i pokaże treść, która zostanie wyrenderowana.
Plik Markdown
Front matter ({f})
Znalezione pola najwyższego poziomu
Brak prostych linii key: value na najwyższym poziomie.
Treść
Brak front matter: pierwsza linia to nie --- ani +++, więc cały plik jest traktowany jako treść.
Blok otwarty przez {d} nigdy nie zostaje zamknięty. Dodaj pasującą linię {d} po ostatnim polu.