Notatki markdown przez wygasający link. Własne narzędzie w 2 godziny

Wysyłam ludziom pliki .md po kilkanaście razy w tygodniu. Dla mnie to naturalny format notatki, dla odbiorcy plik, którego system nie umie otworzyć, a jak już otworzy, to w notatniku, z gwiazdkami i krzyżykami zamiast formatowania. Zbudowałem więc własny serwis, który zamienia taki plik w czytelną stronę pod losowym adresem znikającym po zadanym czasie. Zajęło to niecałe dwie godziny i nie napisałem w tym czasie ani jednej linijki kodu.

Z tego artykułu dowiesz się:

• jak wygląda droga od „wkurza mnie to" do wdrożonego narzędzia, krok po kroku,
• dlaczego świadomie odpuściłem kilkanaście gotowych usług, które robią prawie to samo,
• na czym można się przewrócić, budując coś takiego z agentem, i jak tego uniknąć.

Problem: markdown jest wygodny dla mnie, nie dla odbiorcy

Notatki, konspekty zajęć, plany projektów i briefy trzymam w markdownie. Jeden format, wszędzie ten sam, otwiera się w czymkolwiek.

Tak mi się wydawało.

Odbiorca dostaje załącznik .md i zaczyna się. Windows pyta, czym to otworzyć. Ktoś odpala to w notatniku i widzi ścianę tekstu z krzyżykami. Ktoś inny w ogóle nie pobiera, bo nieznane rozszerzenie w załączniku wygląda podejrzanie.

Widziałem ten sam odruch u kursantów, u studentów i u klientów. Za każdym razem kończyło się tym samym: eksport do PDF-a, ręcznie, żeby dokument wyglądał jak dokument.

Robiłem to tygodniami, zanim policzyłem, ile czasu na to schodzi.

Dlaczego nie wziąłem gotowca

Narzędzi do dzielenia się markdownem są dziesiątki. HackMD renderuje ładnie i ma przycisk publikacji. StackEdit działa od 2013 roku i nie wymaga konta. Rentry pozwala wkleić tekst i od razu dostać link. GitHub Gist też zadziała, tylko dla nieprogramisty wygląda obco.

Każde z nich rozwiązuje mój problem w jakichś siedemdziesięciu procentach. Brakujące trzydzieści to za każdym razem coś innego.

Chciałem czterech rzeczy naraz:

• adresu na własnej domenie, bo wysyłam to klientom i studentom,
• linku, który znika sam po zadanym czasie, bez sprzątania po sobie,
• możliwości, żeby odbiorca poprawił notatkę i odesłał mi swoją wersję,
• jednej komendy w terminalu, która wyśle plik prosto z mojego vaulta, bez otwierania przeglądarki.

Żadna usługa nie dawała kompletu. A wystawianie własnych notatek na cudzy serwer, żeby dostać siedemdziesiąt procent tego, czego chcę, przestało mi się opłacać w momencie, w którym zbudowanie stu procent zajmuje popołudnie.

Miałem też punkt zaczepienia. Na tej stronie, w sekcji Tools, stoi konwerter markdowna do HTML. Renderuje i pokazuje, ale nie zapisuje, nie importuje i nie eksportuje. Silnik był gotowy, brakowało wszystkiego dookoła.

Krok po kroku: od problemu do wdrożonego narzędzia

Cała robota poszła w Claude Code. Nie na żywioł.

1. Brainstorming, zanim padnie pierwsza linijka

Zacząłem od wtyczki do brainstormingu, która wymusza rozmowę przed pisaniem kodu. Agent zadaje pytania pojedynczo i nie pozwala przejść dalej, dopóki nie wiadomo, co właściwie budujemy.

Tam wyszły decyzje, których sam bym w locie nie podjął. Czy link ma być odgadywalny. Co się dzieje, gdy odbiorca zapisze cudzą notatkę. Czy data wygaśnięcia przesuwa się przy edycji.

Ostatnia okazała się ważniejsza, niż wyglądała. Gdyby termin przesuwał się przy każdym zapisie, notatka na dobę żyłaby w nieskończoność, o ile ktoś ją regularnie otwiera i poprawia. Ustaliłem, że termin stoi w miejscu i rusza się tylko wtedy, gdy autor sam sięgnie po selektor czasu.

2. Spec, potem plan, dopiero potem kod

Z rozmowy powstał dokument opisujący, co narzędzie robi i czego nie robi. Z dokumentu lista zadań. Dopiero z listy zadań kod.

Trzy kroki zamiast jednego. Brzmi jak zbędna biurokracja przy narzędziu, które ma pięć ekranów.

Nie jest. Agent, który dostaje spec, nie dopisuje rzeczy, o które nikt nie prosił, i nie gubi ustaleń z początku rozmowy przy trzydziestym poleceniu. Cały ten materiał został w repozytorium i po miesiącu wciąż wiem, dlaczego coś działa tak, a nie inaczej.

3. Realizacja

Osiemnaście commitów. Pierwszy o 10:22, ostatni o 12:18. Godzina i pięćdziesiąt sześć minut.

Wyszło z tego około tysiąca linii: PHP z SQLite, bez frameworka i bez Composera. Baza leży poza katalogiem widocznym z przeglądarki. Renderer to markdown-it z wtyczkami na przypisy, listy zadań, indeksy i bloki informacyjne, do tego highlight.js na kolorowanie kodu i DOMPurify na wyjściu.

Ten renderer to dokładnie ten sam kod, który stoi w narzędziu w Tools. Jeden z commitów nazywa się wprost „bundle renderera przeniesiony z tools/markdown-html". Nowy projekt zaczął się od czegoś, co już u mnie działało.

4. Wdrożenie

Zwykły hosting współdzielony na dhostingu, wysyłka przez FTP skryptem deploy.sh. Żadnego Dockera, żadnego CI, żadnej chmury z rozliczaniem za żądanie.

Konto FTP wchodzi ponad katalog publiczny, więc logika PHP i baza siedzą tam, gdzie przeglądarka nie sięgnie. Skrypt wdrożeniowy odmawia wysyłki, jeśli zbudowany renderer jest starszy niż jego źródło, bo serwer produkcyjny nie ma Node'a i nie zbuduje go sam.

5. Spięcie z agentem

Na koniec skill, którego używam najczęściej. Jedna komenda w terminalu:

md:wrzuc 30_WIKI/2026/202608/plan-warsztatow.md --czas 7d

Wraca link i data wygaśnięcia. Tyle.

Można dorzucić hasło przełącznikiem --haslo. Klucz API skrypt znajduje sam, czytając konfigurację projektu, więc zmiana klucza w jednym pliku wystarcza i nie trzeba nic synchronizować.

Co dokładnie powstało

Najciekawsza jest ta ostatnia linia i to ona rozwiązała mój czwarty warunek.

Kto tworzy notatkę, dostaje sekret zapisany w swojej przeglądarce. Nie ma go w adresie, więc nie da się go przypadkiem przekazać dalej razem z linkiem. Póki masz ten sekret, zapis nadpisuje twoją notatkę i link się nie zmienia.

Kto otworzy cudzą notatkę w trybie edycji i zapisze, dostaje własną kopię pod nowym adresem. Oryginał zostaje nietknięty.

Student poprawia mój konspekt i odsyła mi swoją wersję. Ja widzę obie. Nikt nie musi zakładać konta, a po tygodniu obie znikają same.

Typowe pułapki

Tu jest różnica między „działa u mnie" a „można to wystawić ludziom". Sześć rzeczy, na których łatwo się przewrócić.

Sekrety zastępcze zostawione na produkcji. Kod ma wartości domyślne z dopiskiem „do podmiany". Zna je każdy, kto zajrzy do repozytorium. Zostawione na serwerze oznaczają, że da się podrobić ciasteczko odblokowujące notatkę zabezpieczoną hasłem. Własne, losowe sekrety w pliku poza repozytorium to pierwsza rzecz przed wdrożeniem, nie ostatnia.

HTML w treści od nadawcy. Markdown pozwala wstawić surowy HTML. Nadawca kontroluje treść, odbiorca jej nie kontroluje, więc renderer ma wyłączone przetwarzanie HTML, a wynik i tak przechodzi przez sanityzację. Dwie warstwy, bo jedna to za mało.

Cache plików statycznych. Serwer każe przeglądarce trzymać CSS i JavaScript przez trzydzieści dni. Po wdrożeniu widzisz starą wersję i nie rozumiesz dlaczego. Doklejenie czasu modyfikacji pliku do adresu załatwia sprawę.

Opcache po wdrożeniu. Przez mniej więcej minutę po wysyłce serwer podaje jeszcze poprzednią wersję kodu. Jeśli zaraz po deployu widzisz stare zachowanie, to zwykle nie błąd, tylko cache. Odczekaj i odśwież.

Certyfikat SSL. Na tym hostingu wystawia się go ręcznie w panelu. Skrypt wysyłający sprawdza certyfikat przed wysłaniem treści i odmawia, jeśli coś się nie zgadza. Wolę czytelny komunikat niż notatkę wysłaną nieszyfrowanym połączeniem.

Limity liczone nie tam, gdzie trzeba. Limit sześćdziesięciu zapisów na godzinę dotyczy tylko nowych notatek. Poprawianie własnej limitu nie zużywa, bo wymaga sekretu wydanego przy tworzeniu, które już przez limit przeszło. Bez tego rozróżnienia własna edycja blokowałaby ci własne narzędzie.

To wszystko rzeczy, które w gotowej usłudze robi za ciebie ktoś inny. Budując swoje, przejmujesz je razem z narzędziem. Nie są trudne, ale trzeba o nich wiedzieć.

Podsumowanie

• Wysyłanie .md osobom spoza branży nie działa i nie zadziała. Odbiorca chce zobaczyć dokument, nie plik do otwarcia,
• gotowe usługi rozwiązują ten problem w siedemdziesięciu procentach, a brakujące trzydzieści za każdym razem gdzie indziej,
• niecałe dwie godziny, osiemnaście commitów, około tysiąca linii i zero linijek napisanych ręcznie. Cała robota to rozmowa z agentem, spec, plan i akceptacja kolejnych kroków,
• najwięcej dała pierwsza pół godziny, w której nie powstał żaden kod, tylko odpowiedzi na pytania, czego to ma nie robić,
• narzędzie stoi otwarte pod adresem md.damianslimak.pl i możesz z niego korzystać. Nie musisz zakładać konta.

Nie chodzi o to, żebyś zbudował sobie akurat to. Chodzi o rachunek, który się zmienił.

Każdy drobiazg, który cię uwiera raz w tygodniu i przy którym mówisz sobie „musi być na to jakiś program", jest dziś popołudniem rozmowy z agentem. Nie tygodniem pisania kodu i nie kolejną usługą, do której wysyłasz swoje dane.

Zacznij od najmniejszej rzeczy, która cię wkurza. Nie od aplikacji, o której marzysz.

P.S. Najtrudniejsze w tym projekcie nie było nic technicznego. Najtrudniejsze było przyznanie przed samym sobą, jak długo eksportowałem te notatki ręcznie, zamiast poświęcić jedno popołudnie na to, żeby przestać.

Damian Ślimak. Twój Nawigator w chaosie AI.