Aby w całości wyświetlić długi wiersz kodu Markdown, zachowaj kod bez zmian i dostosuj sposób jego prezentacji. Ten poradnik pomoże użytkownikom Maca zdiagnozować obcięte przykłady, włączyć zawijanie w widoku Reading w Obsidianie oraz zrozumieć, jak zachowają się one na GitHubie.

Co decyduje o zawijaniu wiersza kodu?

Blok kodu wydzielony znacznikami zachowuje kod jako dosłowną treść. CommonMark definiuje znaczniki otwierające i zamykające oraz sposób parsowania treści, ale nie udostępnia przenośnego przełącznika zawijania długich wierszy. Aktualna specyfikacja odpowiada wersji 0.31.2. Specyfikacja CommonMark, bloki kodu wydzielone znacznikami.

GitHub Flavored Markdown stosuje te same podstawowe zasady dotyczące bloków kodu wydzielonych znacznikami. Jego specyfikacja również nie wymaga instrukcji zawijania w ciągu informacyjnym znacznika. Dodanie wrap po nazwie języka nie zapewnia więc przenośnego sposobu zawijania. Opublikowana specyfikacja GFM określa swoją wersję jako 0.29-gfm; nie należy mylić tego numeru wersji z aktualną wersją CommonMark. Specyfikacja GitHub Flavored Markdown.

Na potrzeby tego zadania rozróżnij trzy rezultaty:

Rezultat Co widzi czytelnik Czy wymaga zmiany źródła przykładu?
Zawijanie wizualne Jeden wiersz źródłowy zajmuje kilka wierszy wyświetlania Nie
Przewijanie w poziomie Wiersz wykracza poza widoczny obszar, ale nadal można do niego dotrzeć Nie
Ręczne podziały wierszy Przykład zawiera dodatkowe wiersze źródłowe Tak

W praktyce wybierz zawijanie, jeśli chcesz widzieć cały wiersz w obrębie panelu, albo przewijanie, jeśli ważne jest zachowanie wyrównania. Przy ręcznych podziałach trzeba dodatkowo sprawdzić, czy przykład nadal oznacza to samo.

Rozróżnienie między źródłem a prezentacją jest wyraźnie określone w CSS: przetwarzanie białych znaków wpływa na renderowanie, nie zmieniając danych źródłowego dokumentu. Dlatego zawijanie wizualne to dobry punkt wyjścia, gdy przykład ma pozostać kopiowalny jako jeden wiersz. Moduł CSS Text Level 3.

Najpierw sprawdź, czy przykład zniknął, czy tylko jest poza widokiem

Zanim zmodyfikujesz długie polecenie lub wyrażenie, sprawdź źródło. W Obsidianie wybierz Source mode za pomocą kontrolki trybu edycji. Aby porównać renderowany wynik na Macu, użyj Cmd+E, by przełączać się między edycją a Reading view. Obsidian odróżnia te widoki od Live Preview, który jest trybem edycji. Widoki i tryb edycji.

Użyj tego przykładowego testu w osobnej notatce. Skopiuj wewnętrzną treść Markdown wraz z otwierającym i zamykającym wierszem z trzema znakami backtick. Treść to zwykły tekst, a nie polecenie do wykonania.

```text
BEGIN sample=amber notebook=desktop layout=wide description=This synthetic example contains a deliberately long line so you can check whether the final marker remains visible when the note pane becomes narrow END
```

Zwęź panel notatki i poszukaj END. Jeśli pojawia się w kolejnym wierszu, zawijanie działa. Jeśli można go zobaczyć po poziomym przewinięciu bloku, treść jest dostępna dzięki przewijaniu. Jeśli nadal nie można do niej dotrzeć, porównaj renderowany blok ze źródłem, zanim uznasz, że tekst został usunięty.

Ten test rozdziela dwa problemy wymagające różnych rozwiązań: brakująca treść źródłowa wymaga przywrócenia przykładu, a obecna, lecz niedostępna treść wymaga dostosowania wyświetlania. Nie zmieniaj testu podczas sprawdzania ustawień, aby można było powiązać poprawę ze zmienionym ustawieniem.

Sprawdź też znaczniki. Znacznik zamykający musi używać tego samego znaku co otwierający i zawierać co najmniej tyle samo znaków. Znacznik pasujący do znaczników bloku wewnątrz przykładu może zamknąć blok przedwcześnie. Specyfikacja CommonMark, bloki kodu wydzielone znacznikami. Przy omawianiu składni Markdown zewnętrzny znacznik złożony z czterech znaków backtick może wyświetlić wewnętrzny blok z trzema takimi znakami, jak powyżej. Tworzenie i wyróżnianie bloków kodu.

Zanim dodasz CSS, zapewnij notatce w Obsidianie więcej miejsca

Otwórz Settings → Editor i znajdź Readable line length. Obsidian opisuje to ustawienie jako ograniczenie maksymalnej długości wiersza. Tymczasowo je wyłącz, a następnie porównaj tę samą notatkę testową przy tym samym rozmiarze okna. To zmiana szerokości; dokumentacja nie opisuje jej jako przełącznika zawijania bloków kodu. Ustawienia.

Jeśli teraz mieści się cały przykład, zmiana szerokości może wystarczyć w układzie pulpitu. Zanim na niej poprzestaniesz, przetestuj węższy panel: dodatkowe miejsce w jednym układzie okna nie przesądza o czytelności w innym.

Nie zmieniaj Strict line breaks, by rozwiązać problem przepełnienia kodu. Obsidian opisuje to ustawienie w kontekście podziałów wierszy Markdown, podczas gdy zawartość bloków kodu wydzielonych znacznikami jest traktowana dosłownie. Rozwiązuje ono inny problem formatowania. Ustawienia, Specyfikacja CommonMark, bloki kodu wydzielone znacznikami.

Zawijanie długich wierszy kodu w widoku Reading w Obsidianie

W przypadku wybranych notatek użyj udokumentowanego mechanizmu fragmentów CSS w Obsidianie i właściwości cssclasses. Poniższy kod to własna modyfikacja oparta na tym mechanizmie i standardowym działaniu CSS. Jest przeznaczony do zwykłych renderowanych bloków kodu wydzielonych znacznikami w Reading view; nie jest wbudowanym w Obsidiana ustawieniem zawijania ani konfiguracją trybu edytora. Fragmenty CSS.

Utwórz i włącz fragment

  1. Otwórz Settings → Appearance → CSS snippets.
  2. Wybierz Open snippets folder.
  3. W zwykłym edytorze tekstu utwórz w tym folderze plik wrap-code.css i zapisz w nim poniższy kod CSS.
  4. Wróć do CSS snippets, wybierz Reload snippets i włącz wrap-code.

To udokumentowane przez Obsidiana kroki instalacji na komputerze. Po włączeniu zapisane zmiany fragmentu są zwykle stosowane automatycznie. Fragmenty CSS.

.wrap-code pre,
.wrap-code pre code {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
  word-break: normal;
}

Dodaj ten blok właściwości na początku notatki testowej. Jeśli notatka już zawiera właściwości, dodaj wrap-code do istniejących wartości cssclasses zamiast wstawiać drugi blok właściwości.

---
cssclasses:
  - wrap-code
---

Obsidian opisuje cssclasses jako sposób stosowania niestandardowego CSS do wybranych notatek. Tutaj .wrap-code ogranicza regułę do tych notatek; pozostałe selektory dotyczą renderowanych bloków tekstu wstępnie sformatowanego i ich zawartości kodowej. Ta reguła nie konfiguruje obszaru edycji. Fragmenty CSS.

Zrozum, co zmienia CSS

Deklaracja white-space: pre-wrap zachowuje białe znaki i podziały wierszy ze źródła, jednocześnie umożliwiając zawijanie wizualne. Deklaracja overflow-wrap: anywhere pozwala również zawinąć w razie potrzeby ciąg, który w przeciwnym razie nie dałby się podzielić, bez wstawiania łącznika. Razem rozwiązują problem zarówno długich wierszy zawierających spacje, jak i długich nieprzerwanych ciągów. Moduł CSS Text Level 3, właściwość CSS overflow-wrap.

Nie zastępuj tych deklaracji wartością white-space: normal: powoduje ona zwijanie białych znaków, przez co może zmienić wizualne wcięcia, które chcesz zachować. Ponadto samo overflow-wrap nie przezwycięży reguły dotyczącej białych znaków, która zabrania zawijania. Właściwość CSS white-space, Moduł CSS Text Level 3.

Wróć do Reading view, zwęź panel i ponownie sprawdź END. Następnie skopiuj treść testową do zwykłego edytora tekstu i porównaj ją z oryginałem. Zamierzony rezultat to kilka wierszy wyświetlania zawierających ten sam pojedynczy wiersz źródłowy. To sprawdzenie kopiowania potwierdza rzeczywiste działanie zainstalowanego renderera i motywu.

Pamiętaj o różnicach między rendererami

Dostosowanie wyglądu Obsidiana nie staje się częścią przenośnej składni Markdown bloku kodu wydzielonego znacznikami. Przenosząc przykład w inne miejsce, przetestuj je niezależnie w docelowym środowisku. Skorzystaj z tego porównania, by ustalić, co trzeba sprawdzić:

Miejsce docelowe Na czym polegać Co sprawdzić osobno
Implementacja CommonMark Udokumentowane parsowanie bloków kodu wydzielonych znacznikami Zawijanie, przewijanie i dostępna szerokość wyświetlania
Markdown renderowany przez GitHub Udokumentowane znaczniki i identyfikatory języków w GitHubie Sposób prezentacji bloków kodu w konkretnym miejscu docelowym
Reading view w Obsidianie Renderowana notatka i włączone lokalne style Czy fragment działa z aktualnym motywem
Live Preview lub Source mode w Obsidianie Wybrany tryb edycji Prezentację w edytorze; powyższy fragment jej nie konfiguruje

Granice składni wynikają ze specyfikacji CommonMark, dokumentacji bloków kodu GitHuba i dokumentacji widoków Obsidiana.

GitHub informuje, że identyfikator języka po otwierającym znaczniku umożliwia wyróżnianie składni. Zmiana text na inny identyfikator języka nie jest więc udokumentowanym sposobem na włączenie zawijania. Zachowaj poprawny identyfikator dla danego przykładu i dostosuj prezentację w rendererze, który za nią odpowiada. Tworzenie i wyróżnianie bloków kodu.

Jeśli nie możesz kontrolować prezentacji w miejscu docelowym, zdecyduj, czy zachować niezmieniony wiersz i korzystać z dostępnych tam sposobów nawigacji, czy przepisać przykład na poprawne, krótsze wiersze źródłowe. Taka zmiana musi być zgodna z językiem lub formatem przykładu; znaczniki Markdown nie sprawią, że dowolnie wstawiony znak nowego wiersza będzie poprawny.

Rozwiąż problem bez usuwania potrzebnej treści przez skracanie

Jeśli reguła w Obsidianie nie przynosi widocznych efektów, wykonaj kolejno następujące czynności:

  1. Sprawdź, czy testujesz w Reading view.
  2. Sprawdź, czy wrap-code.css pojawia się w CSS snippets i jest włączony.
  3. Sprawdź, czy cssclasses w notatce zawiera dokładnie wrap-code.
  4. Wyłącz i włącz fragment ponownie, wyświetlając niezmienioną notatkę testową.
  5. W razie potrzeby tymczasowo wyłącz inne fragmenty i porównaj wynik z domyślnym motywem Obsidiana, by wykryć konflikt stylów.
  6. Powtórz test na właściwym przykładzie, zanim uznasz zadanie za ukończone.

Traktuj regułę selektora jako modyfikację, którą należy sprawdzić w swojej instalacji. Motyw lub wyspecjalizowany renderer bloku może stosować inne style lub inną strukturę. Jeśli zwykły test bloku kodu działa, a rzeczywisty blok nie, ta różnica jest cenną wskazówką: zbadaj renderer rzeczywistego bloku, zamiast pochopnie dodawać podziały wierszy.

Podczas końcowego sprawdzania upewnij się, że można dotrzeć do ostatniego znaku, wcięcia pozostają czytelne, skopiowany tekst odpowiada zamierzonemu źródłu, a przykład działa w widoku, w którym będzie czytany. Zachowaj kompletne źródło, świadomie wybierz zawijanie lub przewijanie i przetestuj każde istotne miejsce docelowe.

Źródła