Zasady pisania elementów treści: Kiedy używać poszczególnych bloków

Każda strona w playbooku SEO opiera się na jednym rozróżnieniu: fragment treści ma cel, podczas gdy jego poziom nagłówka i wygląd wizualny to tylko prezentacja. Niniejsze zasady pisania elementów zamieniają to rozróżnienie w kontrakt produkcyjny. Stosuj je przed zastosowaniem jakiegokolwiek komponentu, konwersją artykułu między systemami publikacyjnymi lub zmianą elementu, który już występuje na opublikowanych stronach.

Szybki przegląd

• Sprawdź bibliotekę elementów według celu, a nie nazwy. Jeśli cel elementu odpowiada zadaniu, które wykonuje sekcja, ten element jest obowiązkowy.
• Używaj zwykłego Markdown dopiero po potwierdzeniu, że żaden typowany element nie reprezentuje celu fragmentu. Dowolny tekst jest rozwiązaniem zastępczym, a nie domyślnym wyborem.
• Napisz najpierw cały artykuł jako zwykły tekst. Zastosuj elementy w osobnej, odgórnej przebieżce strukturalnej, aby kompozycja i znaczniki nie konkurowały o uwagę.
• Traktuj dyrektywę Markdown jako kanoniczną treść autorską. Mechanizmy renderowania Hugo i WordPress mapują te same pola i treść na natywne wyjście platformy.
• Pozostaw istniejące opublikowane strony przy znaczeniu, względem którego zostały zweryfikowane. Zmiana definicji powodująca przełamanie tworzy nową wersję i jawną migrację; nigdy nie następuje cicha reinterpretacja starej treści.

Naczelna zasada pierwszeństwa

Bibliotekę należy sprawdzać według tego, co robi dany fragment, a nie jak autor go nazwał. Nazwy bywają różne: jeden autor zatytułuje sekcję „Czym jest churn?”, inny „Churn wyjaśniony”, a trzeci „Robocza definicja”. Ich cel jest identyczny, więc wszystkie trzy mapują się na ten sam element definicji.

To pierwszeństwo istnieje, ponieważ dowolny tekst i typowany element mogą wyglądać identycznie na ekranie, a jednocześnie zachowywać się zupełnie inaczej w dalszym przetwarzaniu. Stylizowany nagłówek, po którym następuje akapit, może w przeglądarce przypominać pole definicji, ale nie niesie ze sobą tożsamości komponentu. Nie jest w stanie niezawodnie wygenerować strukturalnego wyniku definicji, udostępnić swoich pól innemu mechanizmowi renderowania, zachować semantyki podczas migracji ani zostać znalezionym przez kontrolę jakości pytającą, czy strona zawiera definicję. Typowany element mapuje się na komponent i znany kształt danych; podobny wizualnie dowolny tekst nie mapuje się na nic.

Zasada jest zatem rygorystyczna:

Przed napisaniem lub zatwierdzeniem jakiegokolwiek nagłówka lub bloku treści określ jego cel. Jeśli ten cel pasuje do definicji elementu, użyj elementu. Podobieństwo wizualne, istniejący H2 lub możliwość wyrażenia tych samych słów w akapicie nie czynią dowolnego tekstu równoważnym.

Pierwszeństwo ma charakter semantyczny, a nie wizualny. Strona może nadal zawierać zwykłe nagłówki wewnątrz lub wokół elementu, jeśli jego definicja na to pozwala, ale nagłówek nigdy nie zastępuje typu elementu.

Dowolny tekst a typowany element

Korzystaj z tej ścieżki decyzyjnej, dopóki udostępniony diagram nie będzie gotowy:

1. Określ zadanie fragmentu jednym czasownikiem. Przykłady obejmują: definiuj, ostrzegaj, podsumowuj, porównuj, udowadniaj, instruuj lub zachęcaj do działania. Zapobiega to maskowaniu przez tekst nagłówka rzeczywistego celu.
2. Przeszukaj bibliotekę według tego celu i jego synonimów. Autor szukający tylko dosłownego nagłówka „Czym jest X?” może przeoczyć element definicji, którego strona nazywa się „Pole definicji”.
3. Użyj pasującego elementu, gdy istnieje. Nie porównuj wyglądu ani nie zastanawiaj się, czy Markdown mógłby imitować projekt; zarejestrowane zachowanie jest czynnikiem decydującym.
4. Użyj dowolnego tekstu, gdy żaden cel nie pasuje. Jest to poprawne w przypadku łączących wyjaśnień, argumentacji, analizy, kontekstu narracyjnego i przejść, które należą do głównego nurtu artykułu i nie wymagają odrębnego zachowania komponentu.
5. Zanotuj powtarzającą się lukę. Jeśli ten sam niedopasowany cel pojawia się na kilku stronach, zaproponuj element biblioteki zamiast wymyślać jednorazową dyrektywę lub traktowanie CSS w artykule.

Zwykły Markdown jest w pełni poprawny, gdy słowa stanowią ciągłe rozumowanie artykułu i nie potrzebują niezależnej etykiety, kontraktu danych, interakcji ani ścieżki ponownego użycia. Na przykład dwa akapity wyjaśniające, dlaczego zalecenie wynika z poprzedzających dowodów, to normalna proza. Zwięzły zestaw wniosków na górze strony nie jest normalną prozą tylko dlatego, że można go zapisać jako wypunktowanie; ma on rozpoznany cel elementu przeglądu lub kluczowych wniosków.

Częste nieporozumienia prowadzące do nieprawidłowego oznakowania

Te przypadki są wymienione wprost, ponieważ łatwo przechodzą kontrolę wizualną. Błąd staje się widoczny dopiero wtedy, gdy inny mechanizm renderowania, walidator, indeks wyszukiwania lub konsument danych strukturalnych otrzyma stronę.

Rozróżnienie między kluczowymi wnioskami a szybkim przeglądem jest szczególnie ważne. Używaj kluczowych wniosków, gdy elementy to konkluzje, które czytelnik powinien zapamiętać, co oznacza, że często można je napisać dopiero po powstaniu artykułu. Używaj szybkiego przeglądu, gdy elementy orientują czytelnika co do zakresu lub kolejności przed czytaniem. Wybieraj według tego zadania redakcyjnego, nawet jeśli bieżący motyw sprawia, że oba komponenty wyglądają podobnie.

Składnia dyrektywy i atrybutów

Kanoniczna forma Markdown używa nazwanej dyrektywy blokowej. Atrybuty występują po nazwie dyrektywy w nawiasach klamrowych:

:::nazwa-elementu{klucz=wartość klucz2="wartość ze spacjami" .klasa}
Treść
:::

Atrybuty służą do przenoszenia małych, stabilnych właściwości, które wpływają na znaczenie elementu lub obsługiwaną prezentację. Utrzymanie ich w formacie czytelnym maszynowo zapobiega ukrywaniu konfiguracji w prozie. Używaj klucz=wartość dla wartości bez spacji oraz klucz2="wartość ze spacjami", gdy występują spacje. Wartość atrybutu bez cudzysłowu nie może zawierać spacji. Wiodąca kropka dodaje obsługiwaną klasę, np. .compact; nie jest to miejsce do wymyślania stylowania specyficznego dla strony.

Klucze atrybutów są pisane małymi literami i używają dokładnej pisowni zdefiniowanej na stronie elementu. Wartości logiczne i wyliczeniowe również podlegają kontraktowi danej strony. Nie twórz atrybutu tylko dlatego, że mechanizm renderowania go toleruje: niezadeklarowany atrybut nie ma gwarancji międzylatformowej.

Zamykające znaczniki ::: należą do elementu nadrzędnego. Umieszczaj je w osobnych wierszach, aby parser mógł odróżnić treść od następnego akapitu. Przykłady kodu demonstrujące dyrektywy muszą znajdować się wewnątrz bloków kodu, tak jak na tej stronie, aby Hugo nie interpretował ich jako treści.

Domyślne mapowanie treści

Większość elementów potrzebuje krótkiego tytułu i dłuższej treści. Wymaganie od autorów powtarzania ich jako atrybutów utrudniłoby edycję długiego tekstu i zwiększyło ryzyko błędnego escapowania, dlatego treść zapewnia domyślne mapowanie:

:::przykład
## Konkretny nagłówek

Reszta treści może zawierać akapity, listy, linki i inne treści dozwolone przez definicję elementu.
:::

O ile strona elementu wyraźnie nie zastępuje tej reguły, pierwszy nagłówek w treści mapuje się na title, a wszystko po tym nagłówku mapuje się na content. Znacznik nagłówka wyraża hierarchię źródła dla edytorów; mapowane pole pozwala każdej platformie renderować odpowiedni semantyczny poziom nagłówka w kontekście.

Tylko pierwszy nagłówek treści podlega temu specjalnemu traktowaniu. Późniejsze nagłówki pozostają częścią content. Jeśli treść nie ma nagłówka, title jest nieobecny; jest to poprawne tylko wtedy, gdy definicja elementu oznacza swój tytuł jako opcjonalny. Jeśli element definiuje nazwane sloty lub inne mapowanie, jego własna strona ma pierwszeństwo przed tym domyślnym ustawieniem, ponieważ mechanizm renderowania musi dokładnie wiedzieć, gdzie należy każdy fragment.

Elementy zagnieżdżone

Niektóre elementy zawierają powtarzalną listę, której wpisy potrzebują własnych atrybutów i treści, takich jak kroki z identyfikatorami, karty z etykietami czy elementy listy kontrolnej ze stanem początkowym. Spłaszczenie tych wpisów w jedną listę Markdown spowodowałoby utratę ich indywidualnych pól, dlatego elementy zagnieżdżone używają jawnej dyrektywy elementu:

:::element-nadrzędny{wariant=kompaktowy}
::element{klucz=wartość}
### Tytuł pierwszego elementu

Wyjaśnienie pierwszego elementu.
::
::element{klucz2="wartość ze spacjami"}
### Tytuł drugiego elementu

Wyjaśnienie drugiego elementu.
::
:::

Kontrakt to ::element{klucz=wartość} … ::: dwa dwukropki otwierają każdy element, nazwa w liczbie pojedynczej to element, a dwa dwukropki go zamykają. Element nadrzędny zachowuje swój zamykający znacznik z trzema dwukropkami. Ta różnica wizualna ma znaczenie, ponieważ czyni zagnieżdżanie jednoznacznym bez polegania na wcięciach, które łatwo ulegają uszkodzeniu podczas kopiowania i wklejania.

Każdy element stosuje to samo domyślne mapowanie treści, chyba że strona elementu nadrzędnego stanowi inaczej: jego pierwszy nagłówek staje się title tego elementu, a reszta staje się jego content. Umieszczaj atrybuty na elemencie, gdy opisują tylko ten element; umieszczaj je na elemencie nadrzędnym, gdy wpływają na kolekcję jako całość.

Linki, obrazy i przyciski w tekście

Przenośne źródło wymaga przewidywalnych ścieżek. Względny adres URL powinien być względny względem głównego katalogu strony, a nie bieżącego pliku Markdown, ponieważ to samo źródło może być renderowane na innej głębokości systemu plików w Hugo lub zaimportowane do WordPress.

• Linki do stron wewnętrznych używają wiodącego i końcowego ukośnika, tak jak link do biblioteki elementów . Nie używaj ../, nie pomijaj wiodącego ukośnika ani nie koduj na stałe domeny produkcyjnej dla strony wewnętrznej.
• Linki zewnętrzne używają pełnego adresu URL https://. Schemat jest częścią miejsca docelowego i nie może być domyślnie przyjmowany przez mechanizm renderowania.
• Pliki źródłowe obrazów znajdują się poniżej cdn-assets/seo-playbook/, a ich ścieżki publiczne zaczynają się od /cdn-assets/seo-playbook/. Dodawaj zatwierdzoną grupę i nazwę pliku dopiero po istnieniu zasobu.
• Tekst alternatywny opisuje informację przekazywaną przez obraz, a nie jego nazwę pliku lub wygląd dekoracyjny. Obraz dekoracyjny używa pustego tekstu alternatywnego, ale stosowna strona elementu musi wyraźnie zezwalać na dekorację.
• Wezwanie do działania w tekście używa :button[Widoczna etykieta]{href="/cel/"}. Tekst w nawiasach kwadratowych to dostępna etykieta, a href podlega tym samym regułom ścieżek wewnętrznych lub zewnętrznych. Używaj przycisku tylko dla faktycznej kolejnej akcji, a nie do wyróżnienia zwykłego linku referencyjnego.

Obraz to treść, a nie obejście nieobsługiwanego układu. Jeśli obraz zawiera niezbędne etykiety, liczby lub instrukcje, powtórz te informacje w dostępnym tekście lub użyj strukturalnego elementu, który je udostępnia. Żądania zrzutów ekranu pozostają komentarzami HTML, dopóki nazwany zasób nie istnieje; nie są publikowanymi odniesieniami do obrazów i muszą ustawiać screenshotsPending = true w metadanych.

Metadane i elementy treści mają różne zadania

Metadane opisują dokument jako dokument. Dyrektywy w treści opisują znaczące bloki w doświadczeniu czytelniczym. Utrzymanie tych warstw oddzielnie pozwala stronom listowania, schematom, routingu i narzędziom publikacyjnym odczytywać metadane bez parsowania widocznej prozy.

Elementy metadanych znajdują się zatem w metadanych: tytuł strony, opis, słowa kluczowe, daty publikacji i aktualizacji, informacje kanoniczne lub aliasy, własność, taksonomia, powiązania playbooka oraz wszelkie zorientowane na schemat kolekcje, które kontrakt strony tam umieszcza, takie jak wpisy FAQ na stronach academy. Te pola nigdy nie są zapisywane jako dyrektywy :::. Widoczny blok, który powtarza niektóre metadane, nie przenosi autorytatywnego pola z metadanych; otrzymuje własny element treści tylko wtedy, gdy ma odrębny cel czytelniczy.

Elementy treści znajdują się w treści: definicje, ostrzeżenia, wskazówki, przeglądy, kluczowe wnioski, listy kontrolne, porównania, bloki dowodowe, przykłady, kroki i wezwania do działania. Są one dyrektywami, ponieważ ich lokalizacja w narracji ma znaczenie. Przeniesienie ostrzeżenia do metadanych odłączyłoby je od fragmentu, który kwalifikuje; ukrycie metadanych w dyrektywie treści uniemożliwiłoby systemom na poziomie dokumentu ich niezawodne znajdowanie.

Metadane są domyślnie wymagane

Metadane napędzają trasy, podglądy, odkrywanie, powiązania i strukturalne wyniki, zanim ktokolwiek przeczyta treść. Pominięte pole może zatem zepsuć systemy, które nigdy nie renderują artykułu. Z tego powodu każdy element metadanych jest wymagany, chyba że jego strona wyraźnie stwierdza, że jest opcjonalny.

Wymagany oznacza wypełniony prawidłową wartością, a nie tylko obecny jako pusty ciąg znaków lub pusta kolekcja. Nie wnioskuj opcjonalności z pominięcia na innej stronie i nie dodawaj wartości zastępczych w celu spełnienia walidacji. Jeśli wymagana wartość nie jest jeszcze znana, strona nie jest gotowa do publikacji. Elementy treści podlegają regułom wymagań odpowiedniego typu postu i stron elementów, a nie temu domyślnemu ustawieniu metadanych.

Najpierw pisz, potem stosuj elementy

Wybór elementu to zadanie klasyfikacyjne, podczas gdy pisanie to zadanie rozumowania. Próba wykonywania obu tych zadań zdanie po zdaniu sprawia, że autor optymalizuje przedwcześnie pod kątem granic komponentów. Typowym rezultatem są słabsze przejścia, płytkie wyjaśnienia dopasowane do rozmiaru pudełka, powtarzające się nagłówki utworzone w celu zaspokojenia znaczników oraz dyrektywy wybrane ze względu na wygodę, a nie dopasowanie celu.

Produkcja odbywa się zatem w dwóch odrębnych przebiegach:

1. Napisz cały artykuł jako zwykły tekst. Uzupełnij argumentację, przykłady, zastrzeżenia, przejścia i zakończenie. Na tym etapie nagłówki mogą opisywać logikę szkicu, ale nie przesądzają o ostatecznym typie elementu.
2. Zastosuj elementy w osobnej, odgórnej przebieżce. Dla każdego nagłówka i bloku określ jego cel, sprawdź bibliotekę, opakuj pasujące sekcje, dodaj zadeklarowane atrybuty oraz potwierdź mapowanie treści i zagnieżdżanie.

Podział poprawia oba wyniki. Proza rozwija się zgodnie z pytaniami czytelnika, a nie rozmiarami pudełek bieżącego motywu, podczas gdy przebieg znaczników może spójnie porównywać podobne bloki w całym dokumencie. Uwidacznia również pominięcia: autor może zobaczyć, że artykuł zawiera ostrzeżenie lub definicję, zanim zdecyduje, jak je zakodować.

Po przebieżce strukturalnej przeczytaj stronę raz, nie patrząc na nazwy dyrektyw. Elementy muszą wspierać spójny artykuł, a nie zamieniać go w stos niepołączonych widżetów. Następnie sprawdź źródło raz, nie oceniając prozy, weryfikując znaczniki, atrybuty, zagnieżdżone elementy, ścieżki i wymagane metadane.

Kontrakt trzech notacji

Element jest definiowany raz przez swój cel, kanoniczne pola, dozwolone wartości, mapowanie treści, zachowanie dostępności, zachowanie danych strukturalnych i wersję. Ta definicja jest źródłem prawdy. Trzy notacje platform są adapterami do niej, a nie trzema niezależnymi projektami komponentów.

Reprezentatywne formy wyjaśniają mapowanie; indywidualna strona elementu publikuje swoją dokładną obsługiwaną nazwę i pola. Autorzy pracują w notacji wymaganej przez ich proces publikacyjny, ale nie zmieniają nazw pól, nie dodają znaczeń specyficznych dla platformy ani ręcznie nie naśladują HTML innego mechanizmu renderowania.

Właściciel elementu utrzymuje kanoniczną definicję i decyduje, czy proponowana zmiana jest zgodna, czy wersjonowana. Opiekunowie Hugo i WordPress są właścicielami swoich adapterów i testują je względem wspólnych zestawów danych: ten sam tytuł, treść, atrybuty, elementy, linki i oczekiwania dotyczące dostępności muszą przetrwać na wszystkich trzech ścieżkach. Właściciele redakcyjni weryfikują cel i przykłady. Żaden opiekun platformy nie może przedefiniować znaczenia redakcyjnego lokalnie; jeśli platforma nie jest w stanie wyrazić kontraktu, jest to błąd adaptera lub proponowana zmiana kontraktu.

Ten model pozwala na różnice w prezentacji tam, gdzie platformy tego wymagają, przy jednoczesnym zachowaniu stabilnej semantyki. Hugo może renderować HTML po stronie serwera, a WordPress może przechowywać komentarz blokowy, ale ostrzeżenie pozostaje ostrzeżeniem, element listy kontrolnej pozostaje elementem, a te same wymagane pola pozostają dostępne w dalszym przetwarzaniu.

Wersjonowanie opublikowanych elementów

Opublikowana treść została zweryfikowana względem znaczenia elementu, które obowiązywało w momencie publikacji. Cicha zmiana tego znaczenia może zmienić ostrzeżenia, dane strukturalne, dostępność lub importy bez ingerencji edytora w stronę. Wersjonowanie chroni tę zgodę redakcyjną.

Stosuj następującą politykę zmian:

• Zgodna zmiana mechanizmu renderowania: Udoskonalenie wizualne, poprawa wydajności lub naprawa błędu, która zachowuje cel, pola, akceptowane wartości, mapowanie treści i znaczenie wyniku, może zostać wdrożona w bieżącej wersji. Istniejące strony otrzymują ją za pośrednictwem mechanizmu renderowania.
• Zgodna zmiana addytywna: Nowy opcjonalny atrybut może dołączyć do bieżącej wersji tylko wtedy, gdy jego brak zachowuje istniejący wynik, a każdy adapter może go bezpiecznie zignorować lub obsłużyć. Definicja i testy platform zmieniają się razem.
• Zmiana przełamująca: Zmienione lub usunięte pole, nowe wymagane pole, zmienione mapowanie treści, zmieniony cel, zmieniona wartość domyślna o skutku semantycznym lub niezgodna struktura zagnieżdżonych elementów tworzy nową główną wersję elementu.
• Wycofanie: Stara wersja pozostaje możliwa do renderowania dla opublikowanych stron. Jej strona elementu identyfikuje zamiennik i ścieżkę migracji; nowe strony używają bieżącej wersji.
• Migracja: Migracja treści jest jawna, określona zakresowo, podglądana w Markdown, Hugo i WordPress oraz redakcyjnie zatwierdzona przed publikacją. Zanotuj, które strony uległy zmianie i dlaczego. Nie pozwalaj, aby mechanizm renderowania odgadywał, jak stara treść powinna być reinterpretowana.

Gdy wersja nie jest zapisana w źródle, element używa wersji bazowej zdefiniowanej w momencie przyjęcia tego kontraktu. Ta domyślna wersja musi pozostać stabilna. Nowe główne wersje identyfikują się za pomocą mechanizmu wersji zadeklarowanego na stronie elementu; nie wykorzystują ponownie składni bez wersji.

Wycofanie również ma znaczenie. Zachowaj poprzedni mechanizm renderowania i reprezentację źródłową, dopóki zmigrowane strony nie przejdą kontroli strukturalnej, wizualnej, dostępności i danych strukturalnych. Jeśli migracja się nie powiedzie, przywróć mapowanie poprzedniej wersji, zamiast spłaszczać element do dowolnego tekstu, co odrzuciłoby semantykę, którą wersjonowanie ma chronić.

Lista kontrolna do przeglądu produkcyjnego

Użyj tego końcowego przeglądu po przebieżce prozy i przebieżce elementów:

• Czy cel każdego bloku niebędącego prozą można określić jednym czasownikiem?
• Czy biblioteka została przeszukana według tego celu i bliskoznacznych synonimów?
• Czy każdy pasujący cel używa swojego typowanego elementu, nawet jeśli H2 i akapit wyglądałyby podobnie?
• Czy każdy pozostały fragment dowolnego tekstu jest częścią ciągłego wyjaśnienia, analizy, narracji lub przejścia artykułu?
• Czy atrybuty są zgodne z {klucz=wartość klucz2="wartość ze spacjami" .klasa}, ze spacjami w cudzysłowie i używane są tylko zadeklarowane klucze?
• Czy pierwszy nagłówek treści mapuje się na title, a reszta na content, chyba że strona elementu deklaruje inne mapowanie?
• Czy powtarzalne elementy potomne używają ::element{klucz=wartość} … ::, z atrybutami nadrzędnymi i elementów umieszczonymi na właściwym poziomie?
• Czy linki wewnętrzne są względne względem głównego katalogu z wiodącym i końcowym ukośnikiem, linki zewnętrzne są bezwzględne, a ścieżki obrazów mieszczą się w zatwierdzonym katalogu obrazów?
• Czy pola metadanych znajdują się w metadanych, nigdy w dyrektywach treści, i czy wszystkie wymagane wartości metadanych są kompletne?
• Czy te same kanoniczne pola można bez strat mapować na Markdown, Hugo i WordPress?
• Czy jakakolwiek zmiana definicji zachowuje stare strony lub wprowadza jawną wersję i migrację?

Ta strona jest warunkiem wstępnym dla każdej indywidualnej strony elementu. Każda definicja elementu musi linkować z powrotem do tych podstawowych zasad, a następnie dokumentować tylko wyjątki specyficzne dla swojego celu: obsługiwane atrybuty, wymagane pola, nadpisania mapowania treści lub elementów, dozwolone zagnieżdżanie, dokładne nazwy platform i historię wersji. Jeśli strona elementu milczy, zastosowanie mają domyślne ustawienia z tej strony.