Frontmatter treści: Pola i metadane SEO

Frontmatter to element strony, którego czytelnicy nigdy nie widzą jako jednego bloku, a od którego zależy każdy system publikacyjny. Nadaje dokumentowi tożsamość, kontrakt renderowania, podgląd wyszukiwania, rejestr własności, daty i dane wejściowe dla schematów. Uszkodzony frontmatter może wybrać niewłaściwy szablon, stworzyć konflikty kanoniczne, zgubić autora lub wyemitować znaczniki sprzeczne z treścią strony.

Żywy okaz to rekord na poziomie dokumentu pokazany jako kod, ponieważ frontmatter nie może stać się dekoracyjnym polem w treści.

+++
entity = "guide-how-to"
id = "reset-api-key"
title = "How to Reset an API Key"
seoTitle = "How to Reset an API Key Safely"
description = "Reset an API key safely, replace it in every dependent service, verify the new credential, and revoke the exposed key without avoidable downtime."
url = "/academy/reset-an-api-key/"
image = "/images/academy/reset-api-key.png"
imageAlt = "API key settings with the Rotate key action highlighted"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "reset API key", "rotate API key", "revoke API key" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/reset-an-api-key/"

[[faq]]
question = "Does rotating an API key revoke the old key immediately?"
answer = "Not necessarily. Confirm the provider's rotation behavior before changing dependent services."
+++

Po co istnieje frontmatter

Dla czytelnika metadane zmniejszają niepewność. Precyzyjny tytuł określa zakres, użyteczny opis zasługuje na kliknięcie, tożsamość czyni twierdzenia odpowiedzialnymi, a daty ujawniają, czy informacje mogły się zdezaktualizować. Te sygnały nie zrekompensują słabej treści, ale ich brak zmusza czytelnika do zgadywania.

Dla maszyn frontmatter zastępuje wnioskowanie nazwanymi wartościami. Szablony mapują pola na tytuły przeglądarki, linki kanoniczne, rekordy osób, daty, kanały, indeksy i JSON-LD bez skrobania prozy. To jest maszynowa ekstrahowalność: ważne fakty mają spójną lokalizację i typ.

Postępuj zgodnie z zasadami pisania elementów: metadane należą na poziomie dokumentu; elementy widoczne dla czytelnika należą w treści. Sygnatura autora może być renderowana z frontmatter, ale jej autorytatywny identyfikator pozostaje tam.

Kiedy go używać — a kiedy nie

Każda indeksowalna strona potrzebuje jednego rekordu frontmatter dla tożsamości, renderowania i routingu. Wersje robocze potrzebują go, gdy trafiają do produkcji, aby walidacja mogła wcześnie wykryć błędy.

Nie ukrywaj faktów dotyczących artykułu w frontmatter. Ograniczenia produktu, ostrzeżenia bezpieczeństwa, ujawnienia afiliacyjne, metody i źródła muszą pozostać widoczne tam, gdzie czytelnicy mogą je ocenić. Ustrukturyzowana wartość nigdy nie zastępuje ujawnienia.

Najwięcej szkód wyrządzają przypadki graniczne:

• Niezależnie zmieniające się etykiety nawigacyjne, teksty kampanii i podpisy społecznościowe to ustawienia kanałów; nie przeciążaj pola title.
• Fakty o organizacji wspólne dla całej witryny należą do rekordu organizacji witryny, a nie kopiowane na każdą stronę, gdzie będą się rozjeżdżać.
• Sekcja pytań i odpowiedzi należy do [[faq]] tylko wtedy, gdy ta sama treść jest renderowana widocznie. Ukryte FAQ tylko w schemacie jest nieprawidłowe.
• Etykieta tematyczna należy do taxonomy; nie może zastępować entity, która identyfikuje typ wpisu dokumentu.
• Przekierowanie należy do konfiguracji routingu lub zatwierdzonego pola aliases. canonical identyfikuje preferowaną wersję; nie przekierowuje odwiedzających.

Gdzie go umieścić

Frontmatter zaczyna się od pierwszego bajtu znacznikami +++ i kończy się na pasującym zamknięciu przed treścią. Żaden nagłówek, komentarz, notatka, shortcode ani blok metadanych nie może go poprzedzać. Pola i tablice TOML należą do tego jednego rekordu.

Treść zaczyna się po zamykającym znaczniku. Frontmatter nie może znajdować się między H1 a wstępem, obok zrzutu ekranu, wewnątrz komponentu ani na końcu. Znak BOM lub przypadkowy komentarz może uniemożliwić rozpoznanie. Zduplikowane klucze, znaczniki YAML i drugie bloki są nieprawidłowe.

Anatomia

Legenda renderowana pozostaje na stronie, aby była czytelna i przetłumaczalna niezależnie od obrazka:

1. Granica: otwierające i zamykające znaczniki +++ definiują jedyny region metadanych.
2. Tożsamość: entity, id, type i url informują systemy, czym jest dokument i gdzie się znajduje.
3. Odkrywanie: title, seoTitle, description, image, imageAlt i keywords wspierają podglądy i wyszukiwanie.
4. Pochodzenie: date, updated, author i reviewedBy określają, kto jest odpowiedzialny i kiedy praca została zasadnie zmieniona.
5. Klasyfikacja: taxonomy łączy stronę z kontrolowanymi kolekcjami tematycznymi bez redefiniowania jej tożsamości.
6. Kontrola duplikacji: canonical wskazuje preferowany publiczny adres URL, gdy równoważne wersje są dostępne gdzie indziej.
7. Ustrukturyzowane kolekcje: każdy [[faq]] tworzy jeden typowany rekord pytania i odpowiedzi do widocznego renderowania i schematu.

Przykłady projektowe

Frontmatter ma warianty kontraktu danych, a nie style wizualne. Zrzuty ekranu łączą rekordy źródłowe z odpowiadającym im podglądem lub sygnaturą autora.

Parametry

Poniższe limity redakcyjne obowiązują nawet jeśli parser akceptuje więcej. „Warunkowe” oznacza wymagane, gdy określony warunek jest spełniony.

Referencja dla poszczególnych pól

Ta referencja definiuje kontrakt publikacyjny dla każdego pola. „Wymagane” oznacza, że walidacja powinna zatrzymać publikację, gdy pole lub jego poprawna pochodna jest nieobecna. „Warunkowe” oznacza, że wymóg jest aktywowany przez określony fakt, taki jak renderowanie obrazu lub przeprowadzenie niezależnej recenzji. Wartość domyślna jest bezpieczna tylko wtedy, gdy daje takie samo znaczenie, jakie redaktor wybrałby świadomie.

Tożsamość i routing

title, h1 i seoTitle

• Przeznaczenie — title nadaje dokumentowi jego trwałą redakcyjną nazwę. h1 kontroluje główny nagłówek na stronie, gdy kontekst układu wymaga innego sformułowania. seoTitle kontroluje tytuł przeglądarki/wyszukiwarki, gdy domyślny tytuł potrzebuje zwięzłego kwalifikatora lub oznaczenia marki. Rozdzielenie ich zapobiega wymuszaniu jednej niezręcznej nazwy dla etykiety nawigacyjnej, nagłówka strony i podglądu wyszukiwania.
• Typ i format — Każdy to string w postaci zwykłego tekstu. title jest wartością źródłową; nieobecne nadpisania muszą do niego wracać. HTML, Markdown, emoji i ręczne znaczniki skracania nie są prawidłowymi wartościami.
• Wymagane? — title jest wymagane na każdej publicznej stronie. h1 i seoTitle są opcjonalne i należy je pominąć, gdy title działa we wszystkich trzech kontekstach.
• Limity — Używaj 30–70 znaków dla title, 20–80 dla h1 i 30–60 dla seoTitle jako pasm redakcyjnych, a nie obietnicy, że interfejs wyszukiwania wyświetli każdy znak. Musi być jeden renderowany H1.
• Kto lub co to konsumuje — Szablony stron, tytuły przeglądarki, adaptery wyszukiwania i społecznościowe, karty nawigacyjne, kanały, schema headline, konspekty dostępności i listowania redakcyjne.
• Zasady — Wszystkie wersje muszą identyfikować ten sam temat, intencję i zakres. Zasadna różnica rozwiązuje ograniczenie kanału: na przykład H1 może brzmieć „Jak rotować klucz API bez przestoju”, podczas gdy krótszy tytuł SEO mówi „Rotacja klucza API: bezpieczny przewodnik krok po kroku”. Późniejsza sekcja Tytuł, H1 i tytuł SEO wyjaśnia test redakcyjny.
• Częste błędy — Powtarzanie słowa kluczowego we wszystkich trzech wariantach, umieszczanie przyrostka marki w H1, zmiana obietnicy w pogoni za kliknięciami, osadzanie bieżącego roku, gdy strona nie jest corocznie aktualizowana, lub tworzenie trzech wartości tylko dlatego, że istnieją trzy pola.

slug i url

• Przeznaczenie — Slug to ostatni segment ścieżki; url to ścieżka publiczna względem witryny, która go zawiera. Razem dają stronie stabilny adres dla czytelników, robotów, linków, raportowania i migracji. Stabilność ma znaczenie, ponieważ każdy zdobyty link i zapisana zakładka staje się zależna od tego adresu.
• Typ i format — Użyj ścieżki z małymi literami i łącznikami, np. /academy/rotate-an-api-key/. To repozytorium rejestruje pełną ścieżkę w url; CMS posiadający osobne pole slug musi wyprowadzić ten sam końcowy segment.
• Wymagane? — Unikalna ścieżka jest wymagana dla każdej publicznej strony. Może być generowana tylko tam, gdzie sekcja ma zatwierdzoną deterministyczną regułę i sprawdzanie kolizji; strony playbooka używają swoich zarejestrowanych wartości url.
• Limity — Preferuj krótki, czytelny slug zachowujący wyróżniający temat, zwykle trzy do ośmiu użytecznych słów. Usuń interpunkcję i puste modyfikatory. Usuwaj słowa stop takie jak „the” lub „a” tylko wtedy, gdy wynik pozostaje naturalny i jednoznaczny; nie ma arbitralnego limitu znaków uzasadniającego uszkodzenie znaczenia.
• Kto lub co to konsumuje — Routing Hugo, linki wewnętrzne, breadcrumbs, generowanie kanoniczne, mapy witryn, kanały, analityka, przekierowania i referencje zewnętrzne.
• Zasady — Traktuj opublikowany slug jako stałe zobowiązanie. Ustalaj go na podstawie trwałego tematu, a nie nagłówka kampanii czy tymczasowego roku. Gdy tytuł się zmienia, ale temat i intencja pozostają, zachowaj stary slug. Jeśli strona faktycznie się przenosi, utwórz nową ścieżkę, zachowaj starą ścieżkę w aliases, zaktualizuj linki wewnętrzne i przetestuj cel przekierowania.
• Częste błędy — Regenerowanie sluga przy każdej zmianie tytułu, upychanie synonimów w ścieżce, pozostawianie dat, które sprawiają, że wiecznie aktualne treści wyglądają na przestarzałe, używanie mieszanej wielkości liter lub podkreślników, tworzenie dwóch URLi różniących się tylko końcowym ukośnikiem oraz zmiana ścieżki bez zachowania starej.

canonical

• Przeznaczenie — Kanoniczny identyfikuje preferowany URL wśród równoważnych lub prawie równoważnych dostępnych wersji. Konsoliduje tożsamość; nie przenosi odwiedzającego ani nie usprawiedliwia niekontrolowanej duplikacji.
• Typ i format — Jeden absolutny URL HTTPS, zawierający docelowy host i znormalizowaną ścieżkę: https://amicited.com/academy/rotate-an-api-key/. Szablon może wyprowadzić samoodniesienie z permalinka strony, gdy witryna ma jeden zaufany host i politykę ścieżek.
• Wymagane? — Każda indeksowalna strona musi emitować jeden kanoniczny. Samo pole jest warunkowe, gdy poprawna samoodnosząca się wartość jest wyprowadzana automatycznie; ustaw jawnie dla zatwierdzonego między-domenowego lub wyjątkowego kanonicznego.
• Limity — Dokładnie jeden cel kanoniczny. Cel musi zwracać udany indeksowalny dokument, używać preferowanego protokołu i hosta oraz reprezentować zasadniczo tę samą treść.
• Kto lub co to konsumuje — HTML <link rel="canonical">, wyszukiwarki, sprawdzanie map witryn i linków wewnętrznych, raporty deduplikacji i identyfikatory URL schematu.
• Zasady — Domyślnie samoodniesienie. Użyj kanonicznego między domenami tylko wtedy, gdy inny wydawca jest właścicielem preferowanego odpowiednika i obie strony dążą do konsolidacji. Użyj przekierowania, a nie kanonicznego, gdy stary URL został zastąpiony i użytkownicy zawsze powinni trafiać na nowy. Utrzymuj zgodność kanonicznego, URL mapy witryny, hreflang, linków wewnętrznych i tożsamości schematu.
• Częste błędy — Kierowanie każdej stronicowanej lub zlokalizowanej strony do ogólnego rodzica, kanonizowanie różnych treści, celowanie w przekierowanie lub stronę błędu, mieszanie HTTP i HTTPS, używanie pola jako zamiennika aliasu oraz zakładanie, że dyrektywy kanoniczne są gwarantowane do spełnienia.

aliases

• Przeznaczenie — aliases zachowuje ścieżki, które wcześniej identyfikowały tę samą stronę, aby przeniesienie nie zamieniło istniejących linków i zakładek w ślepe uliczki. Rejestruje historię ścieżek, a nie tworzy alternatywne indeksowalne tożsamości.
• Typ i format — Tablica TOML ścieżek względnych witryny, np. aliases = [ "/blog/old-api-key-guide/" ]. Każda wartość zawiera wiodący i końcowy ukośnik i musi być unikalna w całej witrynie.
• Wymagane? — Opcjonalne dla nowej strony; wymagane, gdy opublikowana strona przenosi się ze ścieżki kontrolowanej przez witrynę.
• Limity — Uwzględnij każdą znaną poprzednią ścieżkę pierwszej strony, która wciąż otrzymuje linki lub ruch. Nie dodawaj spekulacyjnych wariantów pisowni ani nieograniczonej listy URLi słów kluczowych.
• Kto lub co to konsumuje — Wynik aliasów Hugo, przetwarzanie przekierowań wdrożeniowych tam, gdzie skonfigurowane, kontrola jakości migracji, monitory linków i użytkownicy podążający za starymi URLami. Ponieważ Hugo może emitować stronę aliasu zamiast przekierowania HTTP na poziomie źródła, zachowanie wdrożenia musi być zweryfikowane, a nie zakładane.
• Zasady — Przeniesiona strona utrzymuje działanie starej ścieżki. Każdy alias musi rozwiązywać się w jednym skoku do bieżącej kanonicznej ścieżki. Zaktualizuj linki wewnętrzne do nowego URL, nawet gdy alias działa, i zachowaj alias przy późniejszych edycjach, chyba że udokumentowany system przekierowań go zastępuje.
• Częste błędy — Usuwanie starej strony bez aliasu, łańcuchowanie starej ścieżki przez pośrednią do bieżącej, traktowanie aliasów jako duplikujących się ścieżek publikacji, kierowanie kilku niepowiązanych stron do jednego wygodnego celu lub zakładanie, że lokalny wynik Hugo dowodzi statusu HTTP w produkcji.

type i layout

• Przeznaczenie — Te pola wybierają kontrakt renderowania. type umieszcza stronę w klasie treści ze wspólnymi szablonami i zachowaniem; layout żąda konkretnego szablonu w tej klasie. Prawidłowy wybór zapewnia, że strona otrzyma zamierzoną nawigację, slot treści, zasoby i zachowanie schematu.
• Typ i format — Zarejestrowane stringi małymi literami. Ta strona używa type = "academy". Wartość layout to nazwa bazowa szablonu, np. single, bez rozszerzenia pliku ani nawigacji po ścieżkach.
• Wymagane? — type jest wymagane, gdy lokalizacja treści nie implikuje bezpiecznie zamierzonego typu lub gdy kontrakt playbooka tego wymaga. layout jest opcjonalne i należy je pominąć, gdy domyślny szablon typu jest prawidłowy.
• Limity — Jedna wartość dla każdego pola, wybrana tylko z szablonów utrzymywanych przez witrynę. Nowa wartość to zmiana inżynieryjna, a nie redakcyjna improwizacja.
• Kto lub co to konsumuje — Kolejność wyszukiwania Hugo, szablony, wybór partiali, dołączanie CSS i JavaScript, adaptery schematu i reguły walidacji.
• Zasady — Wybierz typ wpisu i kontrakt renderowania przed pisaniem. Używaj layout tylko dla prawdziwego obsługiwanego wariantu; nie używaj go do kompensowania treści należącej do innego type. Zweryfikuj, że nadpisanie istnieje i akceptuje kształt frontmatter strony.
• Częste błędy — Mylenie redakcyjnego entity z Hugo type, nazywanie pliku szablonu, który nie istnieje, kopiowanie typu strony docelowej na dokument academy, poleganie na wnioskowaniu z folderów podczas migracji i wprowadzanie jednorazowych nazw układów, które omijają wspólne ulepszenia.

Odkrywanie

description

• Przeznaczenie — Opis pomaga wykwalifikowanemu wyszukującemu lub odbiorcy udostępniania zdecydować, czy ta strona odpowiada na potrzebę. To tekst podglądu, a nie skompresowane wprowadzenie i nie miejsce do udowadniania trafności przez powtarzanie.
• Typ i format — Jedno zdanie w zwykłym tekście. Powinno naturalnie wymieniać podstawowy termin, podawać konkretną wartość i dodawać użyteczny zakres, odbiorców, metodę lub rezultat.
• Wymagane? — Wymagane dla każdej indeksowalnej strony w tym playbooku.
• Limity — 150–160 znaków, łącznie ze spacjami. To pasmo spójności redakcyjnej, a nie gwarancja wyświetlania: wyszukiwarki mogą go obciąć lub przepisać fragment z treści, gdy inny fragment lepiej pasuje do zapytania.
• Kto lub co to konsumuje — Tagi meta description, domyślne opisy Open Graph i Twitter, karty listowań, kanały, podglądy CMS, kontrole jakości wyszukiwania i czasami schema description.
• Zasady — Pisz dla kliknięcia od właściwego czytelnika. Uczyń zdanie wystarczająco konkretnym, aby odróżnić stronę od innego wyniku o podobnym tytule. Sekcja Zasady opisu poniżej podaje uzasadnienie i testy odrzucenia.
• Częste błędy — Duplikowanie tytułu, wymienianie słów kluczowych, zaczynanie od „Dowiedz się wszystkiego o”, składanie niepopartego roszczenia bycia najlepszym/najszybszym, używanie niejasnego wezwania do działania, przekraczanie pasma przez niewidoczny przyrostek marki lub zakładanie, że autorski tekst musi pojawić się dosłownie w wynikach wyszukiwania.

keywords

• Przeznaczenie — W tym repozytorium keywords rejestruje zwarty zestaw zapytań i terminologii używany do redakcyjnej kontroli jakości, przeszukiwania korpusu, analizy pokrycia i narzędzi wewnętrznych. Pomaga redaktorom rozpoznać język, którego strona musi używać dokładnie; nie jest obietnicą mechanicznego uwzględnienia każdej frazy.
• Typ i format — Tablica stringów w języku naturalnym, uporządkowana od podstawowego terminu przez znaczące warianty i blisko powiązaną terminologię.
• Wymagane? — Wymagane w ramach tego playbooka, w tym dla stron, których publiczne szablony nie renderują tych wartości.
• Limity — Sześć do ośmiu odrębnych wpisów. Każdy wpis musi reprezentować rzeczywistą frazę zapytania lub niezbędny termin, a nie wariację na poziomie tokenów.
• Kto lub co to konsumuje — Walidatory redakcyjne, inwentarze treści, analiza wyszukiwania i możliwości, wewnętrzne wyszukiwanie i narzędzia migracyjne. Publiczne wyszukiwarki nie używają tego pola jako sygnału rankingowego tylko dlatego, że istnieje.
• Zasady — Utrzymuj zestaw skupiony na zakresie jednej strony. Łącz duplikaty wielkości liter, interpunkcji, liczby pojedynczej/mnogiej i trywialnej kolejności słów. Używaj fraz do sprawdzania pokrycia i terminologii, nigdy do dyktowania nienaturalnego zagęszczenia.
• Częste błędy — Traktowanie pola jako przestarzałego mechanizmu rankingu meta-keywords, dodawanie dziesiątek wariantów, powtarzanie tytułu jako ośmiu prawie identycznych wpisów, wstawianie nazw konkurentów, których treść nie omawia, oraz pozwalanie, aby tablica zastąpiła właściwą taksonomię lub cele promptów.

targetPrompts

• Przeznaczenie — targetPrompts rejestruje pełne pytania lub prośby, które użytkownik może zadać systemowi AI i dla których ta strona powinna być użytecznym źródłem. Cele promptów zachowują kontekst konwersacyjny, który pomijają krótkie frazy słów kluczowych.
• Typ i format — Tablica pełnych stringów w języku naturalnym, np. targetPrompts = [ "Jak rotować klucz API bez przestoju?", "Co powinienem sprawdzić przed unieważnieniem starego klucza API?" ]. Zachowaj brzmienie tak, jak zadałby użytkownik, z uwzględnieniem odbiorców, ograniczeń lub pożądanego porównania.
• Wymagane? — Warunkowe dla stron objętych śledzeniem promptów lub programem widoczności AI; opcjonalne, gdy nie istnieje żaden śledzony zestaw promptów.
• Limity — Używaj małego, zamierzonego zestawu, zwykle jednego głównego promptu i do czterech znaczących wariantów. Prompt może być dłuższy niż słowo kluczowe, ponieważ jego kwalifikatory niosą intencję.
• Kto lub co to konsumuje — Briefy treści, przepływy śledzenia promptów, audyty wyszukiwania i pokrycia, monitorowanie odpowiedzi AI i ocena redakcyjna. Nie jest renderowany jako ukryty tekst wyszukiwania.
• Zasady — Rozdzielaj prompty według rzeczywistej potrzeby informacyjnej, a nie interpunkcji. Słowo kluczowe, takie jak „rotacja klucza API”, nazywa temat; „Jak zespół SaaS może rotować klucz API bez przerywania integracji?” nazywa odbiorców, zadanie i ograniczenie. Strona musi odpowiadać na każdy przechowywany prompt zgodnie z prawdą.
• Częste błędy — Kopiowanie tablicy słów kluczowych do tego pola, fabrykowanie dziesiątek wariantów składniowych, rejestrowanie promptów szerszych niż strona, używanie promptów jako nagłówków treści bez względu na przepływ czytania oraz twierdzenie o pokryciu promptów, gdy odpowiedź zależy od informacji, których strona nie dostarcza.

Zaufanie i pochodzenie

date i updated

• Przeznaczenie — date zachowuje moment pierwszej publikacji strony; updated raportuje ostatnią merytoryczną zmianę lub zakończony przegląd. Dwa pola zachowują historię, pokazując jednocześnie, czy informacje, na których polegają czytelnicy, uległy zmianie.
• Typ i format — Stringi znacznika czasu zgodnie z konwencją witryny, YYYY-MM-DD HH:MM:SS. Utrzymuj jedną politykę strefy czasowej w całym korpusie, aby kanały i porównania pozostały deterministyczne.
• Wymagane? — date jest wymagane dla opublikowanych stron redakcyjnych. updated jest opcjonalne do czasu wystąpienia kwalifikującej się zmiany, a następnie wymagane, jeśli strona prezentuje zmodyfikowaną datę.
• Limity — Jedna wartość każdego. updated nie może poprzedzać date ani znajdować się w przyszłości. Poprawka dokonana minuty po publikacji może być udokumentowana, ale rutynowe rewizje szkicu przed publikacją nie tworzą daty aktualizacji.
• Kto lub co to konsumuje — Widoczne sygnatury i znaczki świeżości, kanały, mapy witryn, schema datePublished i dateModified, audyty aktualności, sortowanie i kolejki redakcyjne.
• Zasady — Resetuj updated przy korekcie faktycznej, zmianie instrukcji, dodaniu lub usunięciu dowodów, zmienionym zakresie, materialnie zmienionej rekomendacji lub udokumentowanym przeglądzie roszczeń wrażliwych na czas. Nigdy nie resetuj dla interpunkcji, formatowania, pracy nad szablonem lub edycji tylko znacznika czasu. Zobacz Daty, autorzy i recenzenci po uzasadnienie polityki.
• Częste błędy — Nadpisywanie oryginalnej daty podczas odświeżenia, datowanie w przyszłości, aby strona wyglądała na świeżą, podbijanie dat bez różnicy w treści, traktowanie automatycznego wdrożenia jako aktualizacji redakcyjnej i brak rejestracji co się zmieniło w prowadzonej historii aktualizacji.

author

• Przeznaczenie — author łączy dokument z odpowiedzialną encją osoby odpowiedzialnej za jego powstanie. Link daje czytelnikowi i maszynie ścieżkę od strony niosącej twierdzenia do utrzymywanej tożsamości, wiedzy specjalistycznej i innych prac.
• Typ i format — Stabilny identyfikator autora, który rozpoznaje się poprzez rejestr autorów witryny do profilu URL i rekordu Person. Na przykład author = "maya-chen" jest prawidłowe tylko wtedy, gdy ten identyfikator się rozwiązuje; nazwa wyświetlana, taka jak "Maya Chen, ekspert SEO", nie jest substytutem linku encji.
• Wymagane? — Wymagane dla merytorycznych stron redakcyjnych. Strony transakcyjne mogą używać zarządzanego właściciela organizacyjnego tylko wtedy, gdy szablon i polityka obsługują ten typ encji.
• Limity — Domyślnie jedna odpowiedzialna osoba prowadząca; używaj udokumentowanej tablicy identyfikatorów tylko wtedy, gdy schemat i szablony sygnatur obsługują prawdziwe współautorstwo.
• Kto lub co to konsumuje — Widoczne sygnatury, linki do profili autora, schemat Article, kanały, raporty własności redakcyjnej, przepływy recenzji i grafy encji.
• Zasady — Rozpoznaj identyfikator przed publikacją. Profil musi identyfikować tę samą osobę, która jest pokazana w sygnaturze i pozostawać aktualny. Przypisz kredyt osobie odpowiedzialnej za treść, a nie osobie, która ją tylko przesłała.
• Częste błędy — Wprowadzanie niepowiązanej nazwy string, używanie „Admin” lub wymyślonego zespołu redakcyjnego, przypisywanie prominentnego dyrektora, który nie tworzył treści, pozwalanie, aby identyfikator rozpoznawał się do nieistniejącego profilu, oraz zmiana autorstwa w celu zasugerowania wiedzy specjalistycznej, która nie była zaangażowana.

reviewedBy, reviewedAt i reviewScope

• Przeznaczenie — Te pola rejestrują niezależną recenzję odrębną od autorstwa. reviewedBy identyfikuje encję recenzenta; reviewedAt określa, kiedy recenzja została zakończona; reviewScope mówi, co recenzent sprawdził, aby odznaka nie sugerowała zatwierdzenia poza dowodami.
• Typ i format — reviewedBy to stabilny identyfikator rozpoznający się do utrzymywanego profilu osoby. reviewedAt używa formatu znacznika czasu witryny. reviewScope to zwięzłe oświadczenie w zwykłym tekście, np. „Kroki rotacji poświadczeń i ostrzeżenia bezpieczeństwa.”
• Wymagane? — Warunkowe, gdy prawo, polityka ryzyka, wrażliwość tematu lub specyfikacja typu wpisu wymaga niezależnej recenzji. Gdy reviewedBy jest obecne, data i zakres recenzji są wymagane jako dane rekordu recenzji, nawet jeśli konkretny szablon przechowuje je w powiązanym rekordzie redakcyjnym, a nie w publicznym frontmatter.
• Limity — Wymieniaj tylko rzeczywistych recenzentów. Zakres powinien być wystarczająco konkretny, aby ujawnić wykluczenia bez stawania się raportem z recenzji. Recenzent musi mieć odpowiednie kompetencje i nie może po prostu powielać roli autora.
• Kto lub co to konsumuje — Komponenty „zrecenzowane przez”, złączenia encji osoby, audyty zarządzania, bramki publikacji wysokiego ryzyka, ustrukturyzowane pochodzenie i dzienniki aktualizacji.
• Zasady — Przeprowadź recenzję po ustabilizowaniu treści, przechwyć ustalenia i rozwiązania w historii redakcyjnej i przeprowadź ponowną recenzję, gdy późniejsze zmiany wpłyną na recenzowany zakres. Niezależność oznacza, że recenzent testuje pracę, a nie popiera własny szkic.
• Częste błędy — Traktowanie korekty redakcyjnej jako recenzji eksperckiej, wyświetlanie recenzenta bez daty lub zakresu, wymienianie osoby, która nigdy nie widziała wersji końcowej, pozostawianie odznaki po materialnym nierecenzowanym przepisaniu oraz sugerowanie zatwierdzenia prawnego, medycznego lub technicznego poza określonym zakresem.

Media i społecznościowe

image i imageAlt

• Przeznaczenie — image wybiera reprezentatywny obraz bohatera i społecznościowy; imageAlt dostarcza funkcjonalny tekst alternatywny, gdy ten zasób jest renderowany jako znacząca treść strony. Utrzymywanie pary razem zapobiega przekształceniu się obrazów odkrywczych w pominięcie dostępnościowe.
• Typ i format — image to rozwiązywalna ścieżka witryny lub zatwierdzony absolutny URL. imageAlt to zwykły tekst opisujący użyteczne informacje obrazu w kontekście strony, a nie jego nazwę pliku czy docelowe słowo kluczowe.
• Wymagane? — Warunkowe według typu wpisu i szablonu. Jeśli strona wymaga bohatera lub dedykowanego obrazu społecznościowego, image jest wymagane. imageAlt jest wymagane, gdy ten obraz renderuje się informacyjnie; czysto dekoracyjne renderowanie musi używać pustego atrybutu alt w szablonie, a nie zmyślonego tekstu opisowego.
• Limity — Używaj jednego reprezentatywnego zasobu. Dla zgodności społecznościowej dostarcz źródło 1200 × 630 pikseli w oczekiwanym współczynniku przycięcia, trzymaj ważną treść z dala od krawędzi i utrzymuj imageAlt zwięzłe — zwykle 5–160 znaków. Plik musi istnieć, zanim zostanie przywołany.
• Kto lub co to konsumuje — Komponenty bohatera, karty listowań, tagi Open Graph i Twitter, pola obrazu schematu, kanały, potoki obrazów, czytniki ekranu, gdy widoczne, i kontrola jakości zasobów.
• Zasady — Wybierz obraz, który nadal komunikuje po przycięciu środkowym i w rozmiarze miniatury. Opisz jego funkcję w kontekście: „Ustawienia klucza API z podświetloną akcją Rotate” jest użyteczne; „klucz API” nie. Nie umieszczaj istotnych twierdzeń tylko wewnątrz pikseli.
• Częste błędy — Przywoływanie planowanego zasobu, który nie istnieje, używanie logo jako każdego obrazu artykułu, osadzanie małego tekstu, który staje się nieczytelny przy udostępnianiu, pisanie „obraz”, upychanie słów kluczowych w tekście alternatywnym i zakładanie, że zachowanie alt tekstu społecznościowego i widocznego obrazu jest identyczne na różnych platformach.

Pola Open Graph i Twitter Card

• Przeznaczenie — Metadane społecznościowe kontrolują sposób podsumowania URL po udostępnieniu. Spójny tytuł, opis, URL, typ i obraz pomagają odbiorcom rozpoznać stronę przed kliknięciem i zmniejszają szansę, że platforma wybierze nieistotny zasób.
• Typ i format — W tym repozytorium szablony wyprowadzają og:title i twitter:title z title, opisy z description, URL z permalinka, og:type z kontekstu układu i oba tagi obrazu z image z fallbackiem witryny. twitter:card jest emitowany jako summary_large_image. Są to generowane tagi, nie domyślnie duplikujące pola frontmatter.
• Wymagane? — Wyjściowe tagi są wymagane na publicznych stronach. Osobne nadpisania są opcjonalne i powinny być wprowadzane tylko poprzez udokumentowany kontrakt szablonu; nieobsługiwane ad hoc pola, takie jak ogTitle, nic nie robią.
• Limity — Jeden spójny podgląd na stronę i jeden reprezentatywny obraz 1200 × 630. Utrzymuj pochodne sformułowania w pasmach tytułu i opisu, a następnie przetestuj rzeczywiste przycięcie i zachowanie nakładki na głównych powierzchniach udostępniania.
• Kto lub co to konsumuje — Sieci społecznościowe, klienty komunikatorów, rozwijacze linków, rozszerzenia przeglądarki, narzędzia współpracy i debugery podglądu udostępniania.
• Zasady — Preferuj pochodność, aby twierdzenia wyszukiwania i społecznościowe pozostały zgodne. Zastępuj tylko wtedy, gdy kontekst społecznościowy naprawdę wymaga innego ujęcia, a szablon to obsługuje. Zły obraz kosztuje rozpoznawalność i zaufanie: odbiorca może zobaczyć przestarzały interfejs, inny produkt, mylące twierdzenie lub przycięcie ukrywające temat.
• Częste błędy — Tworzenie pól, których żaden szablon nie czyta, pozwalanie globalnemu fallbackowi maskować brak wymaganego bohatera, używanie portretu lub małego obrazu dla szerokiej karty, zmienianie tekstu społecznościowego, aby złożyć silniejszą obietnicę niż strona, oraz walidowanie tylko źródła HTML, a nie pobranego podglądu.

Klasyfikacja

taxonomy, categories i tags

• Przeznaczenie — Klasyfikacja łączy stronę z zarządzanymi kolekcjami tematów, formatów, odbiorców lub produktów. Zasila użyteczne archiwa i filtry tylko wtedy, gdy każdy słownik ma zadeklarowane znaczenie; w przeciwnym razie etykiety stają się niekontrolowaną stertą synonimów.
• Typ i format — Tablice zarejestrowanych slugów małymi literami. Używaj taxonomy dla kontrolowanego słownictwa tematycznego repozytorium. Używaj categories tylko dla małej wzajemnie zrozumiałej hierarchii redakcyjnej i tags tylko dla zarządzanego przekrojowego słownictwa, gdy te taksonomie są skonfigurowane.
• Wymagane? — Warunkowe w zależności od typu wpisu i projektu archiwum. Strony redakcyjne niosące temat normalnie wymagają jednego lub więcej kontrolowanych terminów; strony narzędziowe mogą nie wymagać żadnego. Pole nie powinno być wypełniane tylko dlatego, że CMS je udostępnia.
• Limity — Dla ogólnej taksonomii, jedna do pięciu wartości na kontrolowany słownik. Każdy termin potrzebuje definicji, właściciela i reguły scalania. Twórz indeksowalne archiwum tylko wtedy, gdy termin reprezentuje trwałe zapotrzebowanie czytelników, a archiwum może zaoferować unikalne wprowadzenie, spójny inwentarz, linki wewnętrzne i bieżące utrzymanie.
• Kto lub co to konsumuje — Strony archiwów, breadcrumbs, filtry, systemy powiązanych treści, nawigacja fasetowa, audyty treści i segmentacja analityczna.
• Zasady — Wybierz najwęższy zarejestrowany termin, który dokładnie grupuje stronę. Utrzymuj mapowanie wariantów liczby pojedynczej/mnogiej, skrótów i pisowni do jednej wartości kanonicznej. Decyduj, czy archiwa są indeksowalne na poziomie słownika, a nie tag po tagu po przypadkowym utworzeniu.
• Częste błędy — Używanie seo, SEO, search-optimization i search engine optimization jako osobnych wartości, dodawanie jednorazowych tagów do opisywania każdego rzeczownika, mylenie typu biznesowego z tematem, generowanie cienkich indeksowalnych archiwów i usuwanie terminów bez migrowania ich członków.

Klucze złączeń playbooka

• Przeznaczenie — playbookPillar, playbookFamily, playbookWave, postTypes, elements, businessTypes, journeyStage i amicitedFeatures to typowane klucze złączeń. Pozwalają jednej źródłowej stronie pojawiać się w generowanych bibliotekach i macierzach bez ręcznego kopiowania kart przez redaktorów. Ta strona jest działającym przykładem: jej filar identyfikuje element, jej rodzina grupuje wskazówki dotyczące metadanych, a jej tablica postTypes deklaruje specyfikacje, które ją konsumują.
• Typ i format — Klucze pojedyncze używają zarejestrowanych slugów małymi literami: playbookPillar i playbookFamily to stringi, playbookWave to liczba całkowita, a journeyStage to kontrolowany string. Klucze relacyjne — postTypes, elements, businessTypes i amicitedFeatures — to tablice zarejestrowanych slugów z odpowiednich rejestrów.
• Wymagane? — playbookPillar i playbookWave są wymagane w rekordach playbooka. playbookFamily jest wymagane, gdy filar ma zarządzane rodziny. Złączenia tablicowe i journeyStage są warunkowe: wypełniaj tylko relacje, które kontrakt strony faktycznie obsługuje.
• Limity — Jeden filar, jedna rodzina w ramach tego filaru, jedna fala i jeden etap podróży, chyba że model jawnie zezwala na wiele etapów. Tablice zawierają unikalne zarejestrowane klucze, a nie etykiety wyświetlania, prozę czy URL.
• Kto lub co to konsumuje — Listowania centrum playbooka, macierze międzyfilarowe, filtry, karty relacji, raporty kompletności, widoki fal wydań i narzędzia wewnętrzne znajdujące odpowiednie możliwości AmICited.
• Zasady — Waliduj każdą wartość względem kanonicznego rejestru. Kierunek ma znaczenie: strona typu wpisu wymienia swoje wymagane elements; strona elementu wymienia odpowiednie postTypes; strona typu biznesowego wymienia użyteczne typy wpisów. Traktuj etykiety jako prezentację, a klucze jako trwałe dane. Zmieniaj nazwę klucza tylko poprzez migrację, która aktualizuje każdą stronę złączenia.
• Częste błędy — Wymyślanie blisko-synonimów, przechowywanie tytułów zamiast slugów, mieszanie liczb całkowitych i stringów dla fal, dodawanie relacji, ponieważ dwie strony nawzajem się wymieniają, pozwalanie na wzajemne sprzeczności w tablicach i tworzenie ręcznie utrzymywanego znacznika listowania, który oddala się od metadanych.

Pola pochodne i strukturalne

schemaType

• Przeznaczenie — schemaType wybiera najbardziej specyficzne obsługiwane mapowanie danych strukturalnych, które dokładnie opisuje widoczną stronę. Mówi adapterowi schematu, który kontrakt słownictwa zastosować; nie zamienia strony w tę rzecz samą deklaracją.
• Typ i format — Jedna zarejestrowana nazwa typu Schema.org, taka jak Article, wybrana spośród typów obsługiwanych przez adapter witryny. Wielkość liter i pisownia muszą być zgodne z rejestrem.
• Wymagane? — Warunkowe. Ustaw tam, gdzie wiele mapowań schematu jest prawidłowych dla tego samego typu Hugo lub gdzie kontrakt typu wpisu wymaga jawnego typu. W przeciwnym razie pozwól szablonowi wyprowadzić bezpieczną domyślną wartość.
• Limity — Jeden podstawowy typ strony, zagnieżdżone encje tworzone przez adapter z rzeczywistej treści. Wybrany typ musi spełniać wszystkie wymagane właściwości i odpowiadać temu, co czytelnik może zobaczyć.
• Kto lub co to konsumuje — Adaptery JSON-LD, walidacja wyników rozszerzonych, kontrola jakości treści i raporty inwentarza schematu.
• Zasady — Wybieraj na podstawie funkcji strony i widocznych dowodów, a nie funkcji wyszukiwania, której pragnie redaktor. Strona how-to bez kompletnej widocznej procedury nie może zdobyć dokładności przez ustawienie typu how-to. Utrzymuj synchronizację URLi schematu, dat, osób i obrazów z ich polami źródłowymi.
• Częste błędy — Wybieranie bardziej szczegółowego typu bez jego wymaganej treści, emitowanie kilku sprzecznych typów podstawowych, kopiowanie wartości schematu z niepowiązanego szablonu, zakładanie, że prawidłowa składnia gwarantuje kwalifikowalność, oraz umieszczanie w JSON-LD twierdzeń, których czytelnicy nie mogą sprawdzić.

Czas czytania

• Przeznaczenie — Czas czytania daje czytelnikowi przybliżone oszacowanie wysiłku. Jest wyprowadzany z końcowej renderowalnej treści, więc oszacowanie zmienia się, gdy zmienia się rzeczywiste obciążenie czytelnicze.
• Typ i format — Obliczona całkowita liczba minut wyprodukowana przez politykę zliczania słów potoku treści. Bloki kodu, tabele, podpisy i osadzone multimedia powinny podlegać jednej udokumentowanej regule zliczania.
• Wymagane? — Wyświetlanie jest opcjonalne według szablonu. Pole frontmatter nie jest dozwolone jako źródło prawdy.
• Limity — Zaokrąglaj konsekwentnie i stosuj rozsądne minimum wyświetlania, np. jedna minuta. Dokładne założenie słów na minutę ma mniejsze znaczenie niż używanie tej samej metody w całej witrynie i oznaczanie wyniku jako oszacowania.
• Kto lub co to konsumuje — Nagłówki stron, karty, kanały, segmentacja analityczna i czytelnicy decydujący, czy rozpocząć długi przewodnik.
• Zasady — Obliczaj po przetworzeniu shortcodów i wykluczonych regionów zgodnie z polityką witryny. Przeliczaj przy każdej kompilacji. Jeśli wideo lub interaktywne zadanie materialnie zmienia czas ukończenia, oznacz to osobno, zamiast zniekształcać czas czytania.
• Częste błędy — Wpisywanie readingTime = 8, zapominanie o aktualizacji po przepisaniu, przedstawianie fałszywej precyzji, zliczanie nawigacji i elementów stałych oraz traktowanie intensywnego wykonawczo how-to jako ośmiu minut czytania bez czasu zadania.

[[faq]]

• Przeznaczenie — [[faq]] przechowuje widoczne pary pytań i odpowiedzi raz, aby strona i wszelkie kwalifikujące się dane strukturalne FAQ nie mogły się rozejść.
• Typ i format — Tablica tabel TOML; każda pozycja zawiera jeden question w zwykłym tekście i jeden samodzielny string answer.
• Wymagane? — Warunkowe, gdy po głównej stronie pozostają autentyczne pytania uzupełniające. Nigdy nie jest wymagane tylko po to, aby wypełnić szablon lub osiągnąć funkcję wyszukiwania.
• Limity — Zwykle cztery do ośmiu użytecznych pozycji na stronach playbooka. Każde pytanie występuje raz, a każda odpowiedź musi być kompletna bez polegania na kolejności akordeonu.
• Kto lub co to konsumuje — Widoczne renderowanie FAQ, schemat FAQPage tam, gdzie kwalifikowalne, nawigacja strony, kontrola jakości treści i ekstrakcja odpowiedzi.
• Zasady — To jest kontrakt odsyłaczy krzyżowych: postępuj zgodnie z Dlaczego FAQ znajduje się w frontmatter i późniejszymi wskazówkami dotyczącymi FAQ, zamiast utrzymywać osobne widoczne i schematowe kopie. Przechowuj tylko pytania, do których każdy czytelnik ma dostęp na stronie.
• Częste błędy — Ukryte odpowiedzi tylko w schemacie, zduplikowane nagłówki przebrane za pytania, promocyjne odpowiedzi, niepoparte twierdzenia, nieaktualne JSON-LD i traktowanie kwalifikowalności do wyników wyszukiwania jako gwarantowanej.

[[lnks]]

• Przeznaczenie — [[lnks]] rejestruje każdy zarządzany link wewnętrzny używany w treści, łącząc jego widoczną kotwicę z miejscem docelowym i utrzymywanym opisem. Rekord czyni linki sprawdzalnymi bez skrobania renderowanego HTML i wspiera migrację oraz kontrolę jakości.
• Typ i format — Tablica tabel TOML z text, path i title. text to dokładna widoczna kotwica, path to względny URL witryny z wiodącym i końcowym ukośnikiem, a title to opis strony docelowej.
• Wymagane? — Wymagane dla każdego wewnętrznego linku w treści objętego tą konwencją treści. Głębokie linki aplikacji i źródła zewnętrzne mają własne rekordy i nie są maskowane jako wpisy [[lnks]].
• Limity — Jeden rekord na wystąpienie linku w treści, gdy ta sama kotwica może wskazywać różne miejsca docelowe; w przeciwnym razie dokładne zduplikowane rekordy należy usunąć. Miejsce docelowe musi istnieć lub znajdować się w zatwierdzonym rejestrze kanonicznych slugów dla skoordynowanego wydania.
• Kto lub co to konsumuje — Walidacja linków wewnętrznych, migracja treści, analiza relacji, generowanie tytułów linków tam, gdzie obsługiwane, i przegląd redakcyjny.
• Zasady — Dopasuj text do kotwicy w treści dosłownie, włączając wielkość liter i interpunkcję wewnątrz linku. Używaj kanonicznej ścieżki względnej witryny. Pisz title jako dokładny opis miejsca docelowego, a nie instrukcje dla bieżącej strony. Aktualizuj rekord i treść razem.
• Częste błędy — Używanie dłuższej wartości text niż rzeczywista kotwica, wymyślanie niezarejestrowanego sluga, pomijanie końcowego ukośnika, rejestrowanie przekierowującej starej ścieżki, opisywanie źródła zamiast miejsca docelowego i pozostawianie rekordu po usunięciu jego linku w treści.

Wymagane a opcjonalne według typu wpisu

Macierz stosuje powyższe kontrakty do dwunastu typów wpisów obecnie zadeklarowanych przez ten element. R oznacza wymagane, C oznacza warunkowe zgodnie z zasadami pola, D oznacza wymagane dane wyjściowe, które mogą być bezpiecznie wyprowadzone, a O oznacza opcjonalne. „Tożsamość” obejmuje entity, id, title, type i stabilną ścieżkę. „Odkrywanie” obejmuje description i keywords; cele promptów pozostają warunkowe dla każdego wiersza. aliases jest zawsze warunkowe przy przeniesieniu, podczas gdy autorski czas czytania nigdy nie jest wymagany.

„Warunkowy recenzent” nie jest pozwoleniem na pominięcie recenzji tam, gdzie wymaga tego dokładność lub ryzyko handlowe. Strony best-X i alternatives wymagają niezależnej recenzji, ponieważ ich rekomendacje mogą materialnie wpłynąć na decyzję i często zmieniają się wraz ze zmianą produktów, cen i kwalifikowalności. W innych wierszach polityka ryzyka, a nie dostępny czas redaktora, aktywuje wymóg. Podobnie, kanoniczny oznaczony D jest nadal wymagany w renderowanym HTML; tylko wejściowy frontmatter może być pominięty, gdy szablon może wygenerować poprawne samoodniesienie.

Walidacja frontmatter

Walidacja powinna automatycznie odrzucać deterministyczne defekty i rezerwować osąd dla pytań zależnych od znaczenia, dowodów lub kompetencji zawodowych. Podział zapobiega dwóm przeciwstawnym błędom: proszeniu recenzentów o łapanie błędów składni, które parser może złapać doskonale, i udawaniu, że reguła liczenia znaków może zdecydować, czy tekst jest uczciwy.

Uruchom deterministyczne sprawdzenia przed recenzją redakcyjną, aby recenzent widział spójny rekord. Następnie sprawdź renderowany HTML, a nie sam frontmatter: prawidłowa wartość źródłowa jest nadal defektem produkcyjnym, jeśli wybrany szablon ją ignoruje, mapuje do niewłaściwego tagu, ukrywa wymagane pochodzenie lub generuje kanoniczny niezgodny z publiczną ścieżką. Publikacja jest kompletna tylko wtedy, gdy źródło, render i zachowanie docelowe są zgodne.

Pole entity

entity odpowiada na pytanie „jakiego dokładnie typu wpisu jest ten dokument instancją?” Nie odpowiada na pytanie „jaki temat omawia ta strona?” To rozróżnienie ma znaczenie, ponieważ dwa dokumenty mogą dotyczyć tego samego tematu, wykonując różne zadania. Wpis słownikowy definiuje „diagnozę”; artykuł blogowy może raportować zmianę w wytycznych diagnostycznych. Jeśli oba używają entity = "diagnosis", systemy dalszego przetwarzania nie mogą niezawodnie wybrać odpowiedniego szablonu, reguł walidacji, grupy analitycznej ani migracji.

Użyj przedrostka grupy plus sluga typu wpisu dla wariantów w rodzinie: guide-how-to, guide-ultimate, comparison-a-vs-b i comparison-alternatives-to-x. Użyj nazwy samej dla samodzielnego typu: product-page lub case-study. Zarejestruj identyfikator raz, utrzymuj go stabilnie i nigdy nie zmieniaj go, ponieważ zmienił się temat lub docelowe zapytanie. Umieść koncepcje tematyczne w taxonomy, a język zapytań w keywords.

Tytuł, H1 i tytuł SEO

Te wartości mogą różnić się w zależności od kontekstu, ale muszą opisywać tę samą stronę. title to trwała domyślna wartość. h1 to widoczny nagłówek i może być bardziej naturalny w kontekście. seoTitle służy przeglądarce i wynikom wyszukiwania i może dodać zwięzły wyróżnik, uzasadniony rok lub przyrostek marki.

Na przykład title = "API Key Rotation", h1 = "How to Rotate an API Key Without Downtime" i seoTitle = "API Key Rotation: Safe Step-by-Step Guide" są zgodne co do jednego zadania. „Free Security Tool” jako tytuł SEO byłoby mylące, ponieważ zmienia obietnicę. Nie twórz różnic tylko po to, aby wstawić więcej słów kluczowych.

Zasady opisu

Opis istnieje, aby pomóc wykwalifikowanemu czytelnikowi zdecydować się na kliknięcie. Utrzymuj go w granicach 150–160 znaków, uwzględnij podstawowy termin naturalnie, podaj konkretną korzyść strony i dodaj znaczący kwalifikator, taki jak odbiorcy, zakres lub rezultat. Napisz jedno płynne zdanie, a nie listę słów kluczowych.

Termin potwierdza trafność; powtarzanie nie dodaje wartości. Nie duplikuj tytułu, nie używaj „Dowiedz się wszystkiego o”, nie składaj niepopartych superlatyw ani nie kończ w połowie myśli. Systemy wyszukiwania mogą nadal wybrać inny widoczny tekst dla danego zapytania.

Daty, autorzy i recenzenci

date zachowuje znacznik czasu pierwszej publikacji. updated rejestruje ostatnią merytoryczną zmianę: korektę faktyczną, nowe dowody, zmienione instrukcje, zmieniony zakres, zmienioną rekomendację lub pełny przegląd potwierdzający roszczenia wrażliwe na czas. Zapisz, co się zmieniło w historii redakcyjnej, gdy polityka tego wymaga.

Poprawianie interpunkcji, zmiana stylu przycisku, przebudowa szablonu lub dotknięcie samego znacznika czasu nie resetuje updated. Przesuwanie daty bez wykonanej pracy jest naruszeniem polityki, ponieważ mówi czytelnikom i maszynom, że treść została odświeżona, podczas gdy nie była. To fałszywe przedstawianie, a nie taktyka wzrostu.

Pola autora i recenzenta przenoszą odpowiedzialne tożsamości do sygnatur i danych strukturalnych. Autor jest odpowiedzialny za pracę. Używaj reviewedBy tylko wtedy, gdy miała miejsce wykwalifikowana recenzja i połącz oba identyfikatory z utrzymywanymi profilami. Strona podstaw zaufania wyjaśnia, jak autorstwo, daty, dowody i jasność encji wspierają zaufanie bez gwarantowania rankingów.

Dlaczego FAQ znajduje się w frontmatter

FAQ to widoczna treść i ustrukturyzowana kolekcja. Przechowywanie go raz w [[faq]] pozwala szablonowi renderować akordeon i identyczne FAQPage JSON-LD, zapobiegając nieaktualnemu ukrytemu schematowi.

Uwzględnij autentyczne pytania uzupełniające widoczne dla każdego czytelnika. Nie duplikuj nagłówków, nie ukrywaj promocji w odpowiedziach ani nie oznaczaj niewyświetlonych pytań. Prawidłowe znaczniki nie gwarantują funkcji wyszukiwania.

Składnia i przykłady kodu

Kontrakt międzyplatformowy mapuje pola, a nie widoczny komponent. Następująca przenośna otoczka jest prawidłowa tylko w pliku wymiany, którego importer rozpoznaje dyrektywy metadanych:

:::frontmatter{entity="guide-how-to" id="reset-api-key" title="How to Reset an API Key"}
description: Reset an API key safely, replace it in dependent services, verify it, and revoke the exposed key without avoidable downtime.
author: maya-chen
:::

Musi być znormalizowana do natywnych metadanych strony podczas importu. Nie jest prawidłowa w treści artykułu produkcyjnego. W Hugo poprawnym mapowaniem jest TOML między znacznikami +++ na pierwszym bajcie, jak pokazano w żywym okazie. Celowo nie ma shortcodu {{< frontmatter >}}: shortcode działałby zbyt późno i w niewłaściwym regionie dokumentu.

W WordPress zmapuj te same kanoniczne pola do zarejestrowanych pól wpisu i meta wpisu, np. post_title, post_excerpt, post_name, _amicited_entity, _amicited_author i _amicited_reviewed_by. Komentarz taki jak <!-- wp:amicited/frontmatter --> lub shortcode [frontmatter] jest nieprawidłowy, ponieważ tworzy blok treści, a nie metadane dokumentu. Importery i edytory mogą prezentować panel metadanych, ale przechowywane wartości muszą pozostać dołączone do rekordu wpisu.

Przykłady

Dobrze: jeden spójny, odpowiedzialny rekord

entity = "guide-how-to"
id = "rotate-api-key"
title = "How to Rotate an API Key"
description = "Rotate an API key safely, update every dependent service, verify the replacement, and revoke the old credential without avoidable downtime."
url = "/academy/rotate-an-api-key/"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "rotate API key", "API key rotation", "revoke API key", "credential security", "API security", "secret rotation" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/rotate-an-api-key/"

To identyfikuje wariant how-to, zachowuje historię, wymienia odpowiedzialne osoby i oddziela temat od tożsamości strony. Znacznik czasu aktualizacji jest poparty udokumentowaną zmianą instrukcji i recenzją.

Źle: tytuł powtórzony jako opis

title = "How to Rotate an API Key"
description = "How to Rotate an API Key"

Opis nie dodaje żadnej korzyści, zakresu ani powodu do kliknięcia. Marnuje też przestrzeń podglądu, która mogłaby odróżnić tę stronę od każdego innego wyniku o tym samym tytule.

Źle: jedna encja użyta ponownie dla dwóch typów wpisów

# wpis słownikowy
entity = "diagnosis"

# przewodnik redakcyjny
entity = "diagnosis"

Wspólny temat zastąpił tożsamość typu wpisu. Użyj zarejestrowanych wartości, takich jak glossary-term i guide-ultimate, a następnie przypisz „diagnosis” poprzez taksonomię lub słowa kluczowe.

Źle: data aktualizacji bez różnicy w treści

date = "2026-01-15 09:00:00"
updated = "2026-08-27 10:00:00" # zmieniła się tylko data

Żadna merytoryczna edycja ani recenzja nie wspiera twierdzenia o świeżości. Pozostaw updated bez zmian lub pominięte, dopóki nie pojawi się prawdziwa zmiana, którą można sprawdzić w historii redakcyjnej.

Znaczniki schematu i dostępność

Metadane dostarczają wartości; szablon pozostaje odpowiedzialny za semantyczny HTML, fokus, kontrast, cel linku i tekst alternatywny.

Zasady pisania

• Utrzymuj identyfikatory stabilne, małymi literami i bezpieczne maszynowo. Nigdy nie recykluj id ani nie zmieniaj po cichu entity po publikacji.
• Używaj zwykłego tekstu w polach podobnych do tytułu. HTML, linki Markdown, dekoracje emoji i wymuszone łamania wierszy nie należą do stringów metadanych.
• Utrzymuj opis na 150–160 znakach, a tablice słów kluczowych na sześciu do ośmiu odrębnych fraz dla tego playbooka.
• Używaj prawdziwych zarejestrowanych osób w polach autora i recenzenta. Nigdy nie twórz ceremonialnego recenzenta ani ogólnej tożsamości „Zespół redakcyjny”, chyba że jest to utrzymywana odpowiedzialna encja.
• Używaj kontrolowanej taksonomii. Warianty pisowni i duplikaty liczby pojedynczej/mnogiej tworzą fragmentaryczne archiwa.
• Przywołuj tylko obrazy, które istnieją i mają prawa publikacji. imageAlt opisuje informacyjną treść obrazu, a nie jego cel SEO.
• Utrzymuj odpowiedzi FAQ bezpośrednie i samodzielne. Twierdzenia wciąż wymagają tych samych dowodów i ujawnień, co proza gdzie indziej na stronie.
• Nigdy nie umieszczaj sekretów, prywatnych notatek, tokenów dostępu, instrukcji embarga, danych osobowych ani niesprawdzonych roszczeń prawnych w publikowalnym frontmatter.

Które typy wpisów używają frontmatter i gdzie

Każdy typ wpisu używa frontmatter na pierwszym bajcie. Wymagana głębokość zmienia się wraz z ryzykiem, intencją i schematem, a nie z projektem wizualnym.

Lista kontrolna QA

• Czy plik zaczyna się od +++, zawiera prawidłowy TOML i zamyka rekord przed treścią?
• Czy entity jest zarejestrowanym dokładnym identyfikatorem typu wpisu, a nie tematem, kampanią lub nazwą witryny?
• Czy id jest unikalne i stabilne, a url zgodny z rejestrem kanonicznych slugów?
• Czy title, opcjonalne h1 i opcjonalne seoTitle opisują tę samą stronę bez mylących zmian zakresu?
• Czy opis ma 150–160 znaków, zawiera podstawowy termin naturalnie i oferuje konkretny powód do kliknięcia?
• Czy każdy przywołany obraz istnieje, a imageAlt jest dokładny dla renderowanego obrazu?
• Czy data publikacji jest zachowana, a każda wartość updated poparta merytoryczną różnicą lub udokumentowaną recenzją?
• Czy identyfikatory autora i recenzenta rozpoznają się do prawdziwych utrzymywanych profili, a wymieniony recenzent faktycznie recenzował pracę?
• Czy słowa kluczowe są ograniczone do sześciu do ośmiu użytecznych fraz, a wartości taksonomii pochodzą z kontrolowanych słowników?
• Czy kanoniczny używa HTTPS, rozpoznaje się do preferowanej strony i jest zgodny z mapą witryny i linkami wewnętrznymi?
• Czy każda pozycja [[faq]] zawiera jedno użyteczne pytanie i samodzielną odpowiedź, które renderują się widocznie w identycznym brzmieniu?
• Czy wygenerowany JSON-LD pasuje do widocznej treści, używa stabilnych identyfikatorów i przechodzi walidację składni bez roszczenia nieobsługiwanych typów?
• Czy sekrety, prywatne notatki redakcyjne, niepoparte twierdzenia i ujawnienia tylko w treści są nieobecne w rekordzie?

FAQ

Czy frontmatter jest widoczny na opublikowanej stronie?

Źródłowy rekord jest ukryty, ale szablony mogą renderować tytuł, osoby, daty i FAQ. Inne pola zasilają podglądy, tagi kanoniczne, kanały, mapy witryn, schemat i systemy wewnętrzne.

Czy pole encji powinno zawierać temat czy typ wpisu?

Identyfikuje dokładny typ wpisu. Wspólne tematy należą do taksonomii i słów kluczowych, a nie w miejsce tożsamości dokumentu.

Czy tytuł, H1 i tytuł SEO mogą się różnić?

Tak. H1 może brzmieć bardziej naturalnie, a tytuł SEO może dodać wyróżnik, ale wszystkie wersje muszą składać tę samą obietnicę.

Kiedy należy zmienić datę aktualizacji?

Zmień ją po merytorycznym przeglądzie faktycznym lub edycji. Nie zmieniaj jej dla interpunkcji, stylizacji, pracy nad szablonem ani odświeżenia tylko daty.

Dlaczego pytania FAQ są przechowywane w frontmatter?

Ustrukturyzowana tablica pozwala jednemu źródłu renderować zarówno widoczne FAQ, jak i pasujące FAQPage JSON-LD. Zapobiega to odchodzeniu schematu od tego, co czytelnicy mogą sprawdzić.