Dla kogo

Dokumentacja w Markdownie, kod z nazwą języka

Clean Clipper odczytuje język bloku kodu z samej strony – z klasy przy ogrodzeniu, z elementu nadrzędnego, ze znaczników kolorowania – i wpisuje go za backticki. Na korpusie technicznym metka przetrwała w 73 ogrodzeniach na 156, wobec 20 i 0 w dwóch porównywanych silnikach. Reszta strony trafia do notatki jako zwykły Markdown, bez kolumny bocznej.

Co się psuje przy kopiowaniu

Dokumentacja to w większości kod i akurat ta część rozsypuje się najbardziej. Ogrodzenie ląduje w notatce gołe: w Obsidianie stoi szara ściana, a w repozytorium wycinek przechodzi przez przegląd bez kolorowania. Więc otwierasz każdą notatkę drugi raz i dopisujesz js, python albo bash nad każdym blokiem. Przy trzech fragmentach to drobiazg, przy trzydziestu stronach to cały wieczór.

To, co stoi wokół kodu, przychodzi nie lepiej. Przełącznik wersji, kolumna boczna i lista „na tej stronie” lądują w środku tekstu, a tabela parametrów zwija się do jednej linii, bo w jednej komórce był przykład kodu. Trzy miesiące później szukasz w notatkach nazwy opcji i najpierw trafiasz na trzy kopie tego samego menu. Notatka jest, tylko nie da się jej czytać.

Później mści się to drugi raz. Wycinek wędruje do wiki zespołu albo do opisu pull requesta i stoi tam szary, bo ogrodzenie nie niesie języka. A kiedy dwie notatki opisują tę samą funkcję z dwóch wersji dokumentacji, żadna nie mówi, o którą wersję chodziło: numer wersji siedzi w adresie, a adres ginie przy kopiowaniu jako pierwszy. Notatka nie odpowiada wtedy na pytanie, tylko odsyła z powrotem na stronę, z której powstała.

Co trafia do notatki

• Ogrodzenie wychodzi jako ```js, a nie gołe – kolorowanie działa w Obsidianie, VS Code i na GitHubie od razu po wklejeniu
• Język jest czytany ze strony: z klasy przy ogrodzeniu, z elementu nadrzędnego, ze znaczników kolorowania – nigdy zgadywany z treści kodu
• Tabela parametrów z kodem w komórce zachowuje swoje wiersze, zamiast zwinąć się do jednej linii
• Odsyłacze stają się przypisami [^1], a ich definicje lądują na końcu pliku
• Kolumna boczna, przełącznik wersji i spis „na tej stronie” są usuwane, a nie przerabiane na tekst
• Kod w linii zostaje kodem w linii – także w nagłówkach i w komórkach tabel
• Adres źródła stoi we frontmatterze; przy dokumentacji wersjonowanej to on trzyma informację, którą wersję opisuje notatka
• Na spisie pakietów albo liście wyników rozszerzenie mówi „brak artykułu”, zamiast zapisać trzysta odnośników

Moduł zwraca listę słowników, która wygląda mniej więcej tak:

```python
produkty = [
    {"kategoria": "Owoce", "cena": 4.20, "nazwa": "Jabłko"},
    {"kategoria": "Warzywa", "cena": 6.90, "nazwa": "Szpinak"},
]
```

## Krok 2: przefiltruj listę po kategorii

Zapis dokumentacji krok po kroku

Sześć ruchów i konfiguracja jest z głowy – każda kolejna strona dokumentacji kosztuje już tylko skrót klawiszowy. Cztery pierwsze robi się w ustawieniach, dwa ostatnie na samej stronie.

1. Otwórz ustawienia i w polu folderu docelowego wskaż katalog na notatki z dokumentacji. Może to być katalog wewnątrz drzewa roboczego projektu, na przykład docs/wycinki. Przeglądarka zapyta o zgodę raz i zapamięta ją.
2. Ustaw wzorzec nazwy na {domain}-{title}. Przy dokumentacji domena jest pożyteczniejszą połową nazwy pliku: od razu widać, czy wycinek pochodzi z oficjalnej dokumentacji, czy z wątku na forum.
3. Przestaw obrazy na „pomijaj”. Ilustracje w dokumentacji technicznej to zwykle diagramy, które jako odnośnik na cudzy serwer i tak nic nie dają, a plik zostaje bez linii obrazkowych.
4. Załóż regułę dla dokumentacji, którą czytasz najczęściej: wpisz wzorzec adresu i wybierz podfolder. Od tej chwili źródło referencyjne odkłada się osobno, bez myślenia o tym przy zapisie.
5. Wejdź na stronę dokumentacji i naciśnij Alt+Shift+M. Jeśli potrzebujesz jednej funkcji, a nie całej strony referencyjnej, zaznacz ten fragment wcześniej; przełącznik u góry okna pokazuje, czy przed tobą leży zaznaczenie, czy cała strona.
6. Przejrzyj ogrodzenia w oknie podglądu. Jeśli za backtickami stoi js, php albo bash, strona oznaczyła język; jeśli nie stoi nic, to go nie oznaczyła i dopisujesz go raz ręcznie, zanim plik zostanie zapisany.

Gotowe ustawienia pod dokumentację

Te wartości są nastawione na szukanie, nie na archiwizowanie: przy stronach referencyjnych data znaczy niewiele, za to pochodzenie znaczy dużo. Kto wrzuca wpisy blogowe i dokumentację do jednego folderu, szuka potem dwa razy.

Uruchom migrację, zanim wystartujesz serwer:

```
./bin/migracja --env produkcja
```

```sql
SELECT id, utworzono FROM sesje WHERE wygasa < now();
```

Drugie ogrodzenie niosło `class="language-sql"`. Pierwsze nie niosło
nic i zostało gołe, zamiast dostać etykietę wpisaną na chybił trafił.

Trzy drogi przez dzień

Ocena nieznanej biblioteki

Sprawdzasz, czy biblioteka pasuje do projektu, i czytasz w tym celu stronę startową, konfigurację i rozdział o ograniczeniach. Trzy strony, trzy razy Alt+Shift+M, trzy pliki w podfolderze Dokumentacja – z {domain}-{title} w nazwie, więc wszystkie trzy sortują się obok siebie.

Wieczorem decyzja leży w edytorze, a nie w piętnastu otwartych kartach. Przykłady kodu mają metkę języka, tabela opcji ma swoje wiersze, a adres źródła w każdym frontmatterze mówi, którą wersję dokumentacji czytałeś – numer stoi w ścieżce adresu i razem z nim wchodzi do notatki.

Zapisanie rozwiązania z forum

Odpowiedź na uciążliwy błąd nie stoi w oficjalnej dokumentacji, tylko w wątku z czterdziestoma odpowiedziami. Zaznaczasz tę jedną odpowiedź, która działa, i zapisujesz zaznaczenie: do pliku wchodzi blok kodu razem z metką języka, a nie cały wątek i nie kolumna z podobnymi pytaniami.

Ponieważ reguła dla tej witryny wskazuje inny podfolder niż dokumentacja, przy późniejszym szukaniu od razu widać, że to rozwiązanie pochodzi od osoby postronnej, a nie od autorów biblioteki. To dokładnie ta różnica, którą trzeba umieć uzasadnić w przeglądzie kodu.

Przeniesienie fragmentu do README

W README ma stanąć przykład z oficjalnej dokumentacji. Przestawiasz na ten jeden raz kliknięcie ikony na „schowek”, zapisujesz zaznaczenie z przykładem i wklejasz je wprost do pliku, bez tworzenia notatki.

Wklejone ogrodzenie przychodzi jako ```js i na GitHubie koloruje się od razu. Adres źródła bierzesz z frontmatteru wycinka, jeśli chcesz pod przykładem postawić odnośnik do dokumentacji – ta linia stoi w oknie nad tekstem.

Wobec dzisiejszych sposobów

Alternatywy nie są złe, tylko rozwiązują inne zadania – a przy kodzie nie rozwiązują akurat tej części, na której zależy. Ostatni wiersz mówi też, ile kosztuje ta droga.

Kiedy coś idzie nie tak

Dlaczego za moimi backtickami nie ma nazwy języka?

Bo strona sama jej nie podaje. Clean Clipper czyta klasę, którą przy ogrodzeniu zostawił mechanizm kolorowania witryny, i nie zgaduje z treści kodu – na korpusie technicznym taką klasę niosły 73 ogrodzenia na 156. Przy pozostałych ogrodzenie zostaje gołe i to jest właściwa odpowiedź: zmyślona metka włącza kolorowanie dla niewłaściwego języka, co jest gorsze niż jej brak.

Dlaczego na stronie głównej dokumentacji pojawia się „brak artykułu”?

Bo żadnego tam nie ma. Strona przeglądowa składa się prawie wyłącznie z etykiet odnośników, a rozszerzenie sprawdza gotowy Markdown: jeśli ponad jedna czwarta znaków siedzi w odnośnikach, zapis zostaje odmówiony. Zejdź poziom niżej, na stronę z właściwym tekstem, i zapis pójdzie.

Dokumentacja buduje się skryptem – dlaczego brakuje połowy treści?

Zapisywany jest DOM w stanie, w jakim stoi w chwili kliknięcia. Dokumentacja jednostronicowa zapisze się więc poprawnie, ale zakładki i zwijane sekcje, które są zamknięte, często w ogóle nie istnieją w DOM. Rozwiń sekcję i przełącz się na potrzebną zakładkę, zanim naciśniesz skrót.

Dlaczego ramka z ostrzeżeniem zamieniła się w cytat blokowy?

Bo Markdown nie ma standardowej składni na ramki informacyjne. Treść zostaje w całości, ginie tylko etykieta „uwaga” albo „ostrzeżenie” – ramka staje się >. W Obsidianie da się z tego zrobić callout jedną linią, ale rozszerzenie nie decyduje tego za ciebie.

Czego nie robi

Nie zgaduje języka ogrodzenia, którego strona sama nie oznaczyła: tam, gdzie witryna wydaje kod bez klasy, ogrodzenie zostaje gołe i jest to decyzja świadoma – zmyślona metka kosztuje więcej niż brakująca. Nie przechodzi po całej witrynie z dokumentacją: jedna strona naraz, ta, na której stoisz, bez robota i bez trybu wsadowego. Nie pobiera diagramów ani zrzutów ekranu – obrazy zostają odnośnikami do pierwotnej witryny. A na stronach, które chroni sama przeglądarka, jak chrome:// i sklep z rozszerzeniami, nie uruchamia się wcale.

Pytania