Wcięcia Markdown: zagnieżdżone listy, akapity i kod
Popraw wcięcia Markdown dzięki przykładom podlist, list numerowanych, dodatkowych akapitów i ogrodzonych bloków kodu. Unikaj przypadkowych bloków kodu.
Aby wciąć podlistę Markdown, wyrównaj jej znacznik pod pierwszym znakiem tekstu elementu nadrzędnego. Dla - Element nadrzędny oznacza to dwie spacje, a dla 1. Element nadrzędny trzy. Wcięcia sterują strukturą dokumentu, więc dodanie spacji do zwykłego akapitu może dać zupełnie inny efekt niż zmiana wizualnego wcięcia akapitu w Wordzie.
Zacznij od tego przykładu w przeglądarce Markdown:
- Dokumenty projektu
- Instrukcja instalacji
- Informacje o wydaniu
- Lista kontrolna przeglądu
Instrukcja instalacji i informacje o wydaniu powinny pojawić się pod elementem dokumentów projektu. Lista kontrolna przeglądu powinna pozostać na poziomie zewnętrznym.
Licz od początku treści elementu nadrzędnego
Dla zwykłych elementów listy z jedną spacją po znaczniku korzystaj z tej tabeli wyrównania:
| Początek elementu nadrzędnego | Znaki przed jego tekstem | Wcięcie podlisty |
|---|---|---|
- | 2 | 2 spacje |
1. | 3 | 3 spacje |
12. | 4 | 4 spacje |
100. | 5 | 5 spacji |
Dlatego ogólna zasada „zawsze używaj dwóch spacji” zawodzi w listach numerowanych. Dokumentacja zagnieżdżonych list GitHub ilustruje wyrównanie względem treści nadrzędnej, także dla dłuższych znaczników liczbowych.
1. Przygotuj wydanie
- Potwierdź numer wersji.
- Zaktualizuj dziennik zmian.
2. Opublikuj dokumentację
Zagnieżdżone znaczniki mają trzy spacje na początku. Jeśli zaczynają się przy lewym marginesie, tworzą oddzielną listę, zamiast należeć do pierwszego numerowanego kroku.
Pracując ze starszym procesorem Markdown, sprawdź podgląd pliku także w nim. Tutejsze przykłady są przeznaczone dla parsowania w stylu CommonMark i GitHub Markdown; starsze implementacje mogą inaczej rozpoznawać zagnieżdżone bloki.
Dodaj akapit wewnątrz elementu listy
Dłuższe wyjaśnienie nie potrzebuje własnego punktora. Pozostaw pusty wiersz, a następnie wyrównaj nowy akapit pod tekstem elementu:
1. Przejrzyj instrukcję instalacji.
Potwierdź, że nowy czytelnik może ukończyć konfigurację
bez otwierania dokumentu wewnętrznego.
2. Zatwierdź informacje o wydaniu.
Akapit wyjaśniający należy do kroku pierwszego. Jego dwa wiersze źródła wyświetlają się ciągiem, chyba że dodasz jawny podział wiersza.
Pominięcie trzech spacji może zakończyć listę numerowaną i przekształcić wyjaśnienie w zwykły akapit. W niektórych procesach edycji może to również spowodować rozpoczęcie numerowania kolejnej listy od nowa.
Ten sam wzorzec działa z wypunktowaniem:
- Instrukcja instalacji
Uwzględnij wymagania wstępne, polecenia konfiguracji i krok weryfikacji.
- Informacje o wydaniu
Użyj osobnego akapitu, gdy wyjaśnienie zawiera kilka zdań. Użyj podlisty, gdy zawiera odrębne elementy, które czytelnicy powinni przeglądać pojedynczo.
Umieść kod wewnątrz numerowanego kroku
Ogrodzony blok kodu uwidacznia granice przykładu polecenia. Zastosuj wcięcie do otwierającego ogrodzenia, zawartości i zamykającego ogrodzenia, aby blok pozostał wewnątrz elementu listy:
1. Sprawdź zainstalowaną wersję.
```sh
node --version
```
Zapisz wynik w notatkach z przeglądu.
2. Uruchom kontrole projektu.
Tutaj ogrodzenie zaczyna się pod pierwszą literą słowa Sprawdź. Akapit po ogrodzeniu używa tego samego wyrównania, więc również pozostaje w pierwszym kroku.
Jeśli następny numerowany krok staje się częścią bloku kodu, sprawdź zamykające ogrodzenie. Jeśli kod pojawia się poza listą, sprawdź spacje przed ogrodzeniem. Etykiety języków i dosłowne grawisy opisuje poradnik bloków kodu.
Dlaczego cztery spacje mogą zamienić tekst w kod
Na zewnętrznym poziomie dokumentu, po pustym wierszu, cztery spacje przed wierszem mogą utworzyć blok kodu z wcięciem:
Zwykły akapit.
Ten wiersz jest wyświetlany jako kod.
To zamierzona składnia Markdown, a nie uszkodzone sterowanie wcięciem. Dokumentacja bloków kodu z wcięciem CommonMark wyjaśnia rolę wcięcia i granic bloków.
Wcięty wiersz bezpośrednio po zwykłym tekście akapitu podlega innym ograniczeniom parsowania, więc wstawianie spacji nie jest niezawodnym sposobem tworzenia wizualnego wcięcia akapitu. Wewnątrz list wymagana liczba spacji jest także zależna od elementu zawierającego.
Do cytatu użyj cytatu blokowego. Jeśli zwykły tekst w końcowym raporcie wymaga wcięcia pierwszego wiersza, zachowaj w Markdown zwykły akapit i zastosuj formatowanie akapitu w Wordzie po eksporcie. Te rozwiązania zachowują zamierzone znaczenie treści.
Podczas diagnozowania preferuj spacje
Tabulatory mogą zajmować kilka kolumn wyświetlania, a różne edytory mogą pokazywać je z różną szerokością. Jeśli lista wygląda na wyrównaną w źródle, ale renderuje się nieprawidłowo, włącz pokazywanie białych znaków w edytorze i zastąp początkowe tabulatory wymaganą liczbą spacji.
Nie zastępuj bez zastanowienia tabulatorów wewnątrz przykładów kodu. Tam białe znaki mogą być częścią samego przykładu. Ogranicz porządkowanie do znaczników Markdown i wcięć kontynuacji określających otaczającą strukturę listy.
Unikaj wielokrotnego używania encji niełamliwej spacji do imitowania zagnieżdżonej listy. Tekst może wyglądać na przesunięty w jednym podglądzie, chociaż dokument nadal będzie zbiorem niepowiązanych akapitów.
Sprawdź strukturę przed eksportem do Worda
Przejrzyj reprezentatywną sekcję zawierającą element nadrzędny, podlistę, drugi akapit i ogrodzony blok kodu. W konwerterze Markdown do HTML prawdziwa zagnieżdżona lista znajduje się wewnątrz nadrzędnego elementu listy; samo wizualne przesunięcie nie tworzy tej relacji.
Następnie użyj konwertera Markdown do Worda i otwórz DOCX. Sprawdź, czy numerowanie jest kontynuowane zgodnie z zamiarem, a polecenia pozostają związane ze swoimi krokami. Style list Worda mogą stosować inne odstępy wizualne niż przeglądarka, więc przed udostępnieniem oceń zarówno hierarchię, jak i wygląd końcowego dokumentu.