# Format Markdown: Kompletny przewodnik po pracy z AI i automatyzacją
> Wyczerpujący, praktyczny przewodnik po składni Markdown w kontekście rozwoju AI: CommonMark, hierarchia nagłówków, tabele GFM, escapowanie znaków, prompty systemowe oraz pliki CLAUDE.md.
## 1. Czym jest Markdown: filozofia, CommonMark i dlaczego to natywny język AI
**Markdown** to lekka język znaczników tekstu, stworzony przez Johna Grubera w 2004 roku z prostym celem: pisanie strukturyzowanego tekstu, który pozostaje maksymalnie czytelny w postaci surowej i łatwo konwertuje się do poprawnego HTML-a. Współczesny wzorzec formatu został ustandaryzowany w specyfikacji **CommonMark** i rozszerzony o standard **GitHub Flavored Markdown (GFM)**.
W interakcji ze sztuczną inteligencją (ChatGPT, Claude Code, Gemini, lokalne modele Ollama) to właśnie Markdown jest głównym językiem komunikacji.
```mermaid
flowchart LR
A["Сирий текст Markdown
(Мінімальна вага, чистий UTF-8)"] --> B["LLM / AI-агент
(Точне розуміння семантики)"]
B --> C{"Парсинг та рендеринг"}
C --> D["HTML / Вебсайти
(Заголовки, списки, таблиці)"]
C --> E["DOCX / PDF звіти
(Конвертація через Pandoc)"]
C --> F["Системний контекст
(CLAUDE.md, .cursorrules)"]
```
### Dlaczego duże modele językowe „myślą” w Markdownie
1. **Idealna ekonomia tokenów:** W przeciwieństwie do XML czy HTML, gdzie każdy tag wymaga otwarcia i zamknięcia (`Tekst
`), w Markdownie używa się jedynie minimalnych znaczników kontrolnych lub zwykłych znaków nowej linii.
2. **Jednoznaczność semantyczna:** Symbole `#`, `-`, `>` oraz backticki nie obciążają okna kontekstowego, dając modelowi wyraźną mapę hierarchii myśli.
3. **Naturalność dla streamingu:** Generowanie tekstu słowo po słowie bez skomplikowanych niezamkniętych tagów pozwala renderować formatowanie na bieżąco w interfejsie czatu.
4. **Kontrola wersji w Git:** Pliki `.md` są zwykłymi plikami tekstowymi, więc wszelkie zmiany w bazie wiedzy czy dokumentacji są łatwo śledzone za pomocą `git diff`.
> [!NOTE]
> Formatowanie w Markdownie dzieli się na dwa poziomy: **elementy blokowe** (nagłówki, listy, cytaty, tabele, bloki kodu) oraz **elementy inline** (pogrubienie, kursywa, linki, kod inline). Elementy blokowe muszą być zawsze oddzielone pustą linią.
---
## 2. Hierarchia nagłówków a struktura nawigacyjna dokumentów
Nagłówki stanowią szkielet dokumentu i tworzą spis treści (Table of Contents). W Markdownie poziomy nagłówków oznacza się symbolem kratki (`#`) na początku linii – od jednego do sześciu.
| Poziom nagłówka | Składnia Markdown | Ekwiwalent HTML | Typowe zastosowanie |
| :--- | :--- | :--- | :--- |
| **Poziom 1** | `# Nagłówek` | `` | Tytuł całego artykułu lub dokumentu (tylko 1 na stronę) |
| **Poziom 2** | `## Nagłówek` | `` | Główne sekcje i kluczowe moduły tematu |
| **Poziom 3** | `### Nagłówek` | `` | Podsekcje, kroki instrukcji, poszczególne narzędzia |
| **Poziom 4** | `#### Nagłówek` | `` | Szczegóły podpunktów, parametry, przypisy |
| **Poziom 5** | `##### Nagłówek` | `` | Drobne przypisy techniczne |
| **Poziom 6** | `###### Nagłówek` | `` | Mikro-nagłówki specyfikacji |
### Krytyczna zasada spacji po kratce
Zgodnie ze standardem CommonMark, między symbolem kratki a tekstem nagłówka **musi** znajdować się pojedyncza spacja. Jeśli spacja jest pominięta, większość współczesnych parserów potraktuje wpis jako zwykły hashtag lub surowy tekst.
> [!WARNING]
> Nigdy nie używaj symbolu `#` dla nagłówka pierwszego poziomu wewnątrz treści artykułu, jeśli nagłówek jest już zdefiniowany w metadanych (frontmatter). Na stronie powinien wystąpić dokładnie jeden semantyczny tag ``.
---
## 3. Formatowanie tekstu: pogrubienie, kursywa, przekreślenie i znaki specjalne
Formatowanie inline pomaga zwrócić uwagę na kluczowe terminy i pojęcia.
| Styl wyróżnienia | Składnia Markdown | Wynik wyświetlania |
| :--- | :--- | :--- |
| **Pogrubienie (Bold)** | `**ważny termin**` lub `__termin__` | **ważny termin** |
| **Kursywa (Italic)** | `*akcent*` lub `_akcent_` | *akcent* |
| **Pogrubiona kursywa** | `***krytyczna akcja***` | ***krytyczna akcja*** |
| **Przekreślenie (Strikethrough)** | `~~przestarzała wersja~~` | ~~przestarzała wersja~~ |
| **Kod Inline** | `` `apiKey` `` | `apiKey` |
### Praktyczne niuanse typografii
- **Wyróżnianie wewnątrz słowa:** Jeśli chcesz wyróżnić część słowa, zawsze używaj gwiazdek (`A*cat*meow`), ponieważ podkreślenia wewnątrz słów niektóre procesory ignorują, traktując je jako część identyfikatora zmiennej (`user_profile_id`).
- **Łamanie linii bez nowego akapitu:** Aby dodać złamanie linii (`
`) wewnątrz jednego akapitu, umieść dwie spacje na końcu linii lub skorzystaj z tagu `
`.
- **Komentarze:** Dla notatek, które nie powinny być renderowane na finalnej stronie, używaj składni komentarzy HTML: ``.
---
## 4. Listy i struktury zagnieżdżone: numerowane, wypunktowane oraz checkboxy
Listy porządkują algorytmy krok po kroku oraz zestawy parametrów.
### Listy wypunktowane i numerowane
:::tabs
@tab Lista wypunktowana
```markdown
- Pierwszy punkt planu
- Drugi punkt planu
- Wkładany podpunkt (wcięcie 2 lub 4 spacje)
- Kolejny wkładany podpunkt
- Trzeci punkt planu
```
@tab Lista numerowana
```markdown
1. Pobierz repozytorium
2. Zainstaluj zależności
3. Uruchom serwer deweloperski
```
@tab Interaktywne checkboxy (Task Lists)
```markdown
- [x] Utworzenie pliku konfiguracyjnego
- [x] Konfiguracja połączenia z bazą danych
- [ ] Uruchomienie testów integracyjnych
```
:::
### Dodatkowe bloki wewnątrz list
Aby wstawić akapit, cytat lub blok kodu do punktu listy bez przerywania ogólnej numeracji, zrób wcięcie wynoszące 4 spacje przed każdą podrzędną linią:
```markdown
1. Uruchom proces budowania projektu:
```bash
npm run build
```
> [!NOTE]
> Upewnij się, że zmienne środowiskowe w pliku `.env` są poprawnie skonfigurowane przed uruchomieniem.
2. Sprawdź katalog wyjściowy `dist/`.
```
---
## 5. Linki, obrazy i prawidłowe kodowanie URL-i
Składnia linków i plików multimedialnych opiera się na połączeniu nawiasów kwadratowych i okrągłych.
### Podstawowe konstrukcje linków
- **Zwykły link inline:** `[Dokumentacja Anthropic](https://docs.anthropic.com)`
- **Link z podpowiedzą (title):** `[Claude Code](https://claude.ai "Oficjalna strona")`
- **Autolink:** `` lub ``
- **Obraz:** `[Opis obrazu dla dostępności](/images/diagram.webp "Podpowiedź")`
- **Klikalny obraz-link:** `[](https://example.com)`
### Prawidłowe kodowanie znaków specjalnych w URL-u
Jeśli adres URL zawiera spacje, nawiasy okrągłe lub cyrylicę, bezpośrednie wstawienie zepsuje składnię linku Markdown. Takie znaki należy bezwzględnie zastępować kodami procentowymi (URL percent-encoding):
```markdown
[Artykuł z Wikipedii](https://uk.wikipedia.org/wiki/Комп%27ютер_%28значення%29)
[Artykuł z Wikipedii](https://uk.wikipedia.org/wiki/Комп'ютер_(значення))
```
---
## 6. Kod inline, bloki kodu i podświetlanie składni
Kod i konfiguracje wymagają fontu monospace oraz ochrony przed interpretacją zawartych w nich znaków.
### Kod Inline vs Fenced Blocks
- **Kod Inline:** pojedyncze backticki: `git status`.
- **Eskapowanie backticka w kodzie inline:** owijanie podwójnymi backtickami: `` `npm test` ``.
- **Fenced blocks kodu:** potrójne backticki z obowiązkowym wskazaniem identyfikatora języka.
```typescript
interface UserProfile {
id: string;
username: string;
isActive: boolean;
}
export function formatUser(user: UserProfile): string {
return `@${user.username} (ID: ${user.id})`;
}
```
> [!IMPORTANT]
> **Surowa zasada izolacji promptów:** Wszystkie systemowe prompty lub zasady asystentów (`.cursorrules`, `CLAUDE.md`), które zawierają własne symbole nagłówków (`#`, `##`), **muszą** być owinięte w wydzielony blok kodu ze wskazaniem języka (np. markdown lub text). Pozostawienie ich bez bloku kodu w treści tekstu spowoduje, że wewnętrzne nagłówki promptu trafią do spisu treści (TOC) artykułu i zniszczą nawigację strony.
---
## 7. Cytaty, callouty i poziome separatory
Cytaty tworzy się za pomocą symbolu `>` na początku linii i służą one do wyróżniania myśli, ważnych ostrzeżeń lub cytowania tekstu.
### Standardowe cytaty i wielopoziomowe zagnieżdżenie
```markdown
> To cytat pierwszego poziomu.
>
> > To zagnieżdżony cytat drugiego poziomu wewnątrz poprzedniego.
```
### Współczesne GitHub Alerts (Bloki Callout)
Nowoczesne platformy dokumentacyjne wspierają standaryzowane wyodrębnione bloki z kolorowymi ikonami:
```markdown
> [!NOTE]
> Przydatne informacje referencyjne lub kontekst ułatwiający zrozumienie.
> [!TIP]
> Wskazówka dotycząca optymalizacji, zwiększania efektywności lub najlepszych praktyk.
> [!IMPORTANT]
> Informacja krytyczna, której wdrożenie jest obowiązkowe.
> [!WARNING]
> Ostrzeżenie dotyczące potencjalnych błędów, awarii lub utraty danych.
```
### Poziome separatory
Trzy lub więcej dywizów (`---`), gwiazdek (`***`) lub podkreśleń (`___`) w osobnej linii tworzy poziomą kreskę:
```markdown
Tekst poprzedniego rozdziału.
---
Tekst następnego rozdziału po separatorze.
```
---
## 8. Eskapowanie znaków specjalnych i wbudowany HTML
Gdy trzeba wyświetlić znak składni Markdown jako zwykły znak drukarski, stawia się przed nim odwrotny ukośnik (`\`).
### Lista znaków do eskapowania
| Znak | Nazwa | Przykład eskapowania | Wynik renderowania |
| :--- | :--- | :--- | :--- |
| `\` | Odwrotny ukośnik (Backslash) | `\\` | \ |
| `` ` `` | Backtick | `` \` `` | ` |
| `*` | Gwiazdka (Asterisk) | `\*nie kursywa\*` | \*nie kursywa\* |
| `_` | Podkreślnik (Underscore) | `\_nie pogrubienie\_` | \_nie pogrubienie\_ |
| `#` | Kratka (Hash) | `\# Nie nagłówek` | \# Nie nagłówek |
| `[` `]` | Nawiasy kwadratowe | `\[Nie link\]` | \[Nie link\] |
| `!` | Wykrzyknik | `\!Nie obraz` | \!Nie obraz |
### Bezpieczne użycie HTML
Jeśli standardowy Markdown jest niewystarczający, można skorzystać z tagów HTML, pamiętając jednak o ograniczeniach:
- Tag `
` do wymuszonego łamania linii w tabelach.
- Tag `` do tekstu podkreślonego.
- Blokowe tagi (``, `
`) muszą być oddzielone od kodu Markdown pustymi liniami, a wewnątrz nich składnia Markdown nie działa.
---
## 9. Tabele GitHub Flavored Markdown (GFM) i diagramy Mermaid
Tabele pozwalają porównywać charakterystyki, parametry i konfiguracje.
### Składnia tabel GFM z wyrównaniem
```markdown
| Parametr | Opis funkcjonalności | Wartość domyślna | Status |
| :--- | :--- | :---: | ---: |
| `apiKey` | Tajny klucz autoryzacyjny | `null` | Wymagany |
| `timeout` | Maksymalny czas oczekiwania | `5000` | Opcjonalny |
| `retries` | Liczba ponownych prób | `3` | Zalecane |
```
- `:---` — wyrównanie kolumny do lewej.
- `:---:` — wyrównanie do środka.
- `---:` — wyrównanie do prawej (idealne dla cen i liczb).
### Wizualizacja architektury przez Mermaid
Zamiast ciężkich zrzutów ekranu rastrowego, współcześni deweloperzy używają wbudowanych tekstowych diagramów Mermaid:
```mermaid
sequenceDiagram
autonumber
actor User as Розробник
participant AI as Claude Code / GPT-4o
participant FS as Файлова система
User->>AI: Запит на генерацію документації
AI->>AI: Побудова структури в пам'яті (CommonMark)
AI->>FS: Запис файлу README.md
FS-->>User: Готовий структурований артефакт
```
---
## 10. Markdown w agentach AI: CLAUDE.md, System Prompty i checklista walidacji
W erze autonomicznych agentów AI (Claude Code, Cursor, Windsurf, Devin) Markdown stał się głównym językiem przekazywania kontekstu inżynierskiego.
### Pliki instrukcji projektu (CLAUDE.md / .cursorrules)
Agenci czytają plik główny `CLAUDE.md` przed każdym zapytaniem. Jeśli jest on dobrze sformatowany, model bezbłędnie przestrzega architektury projektu:
```markdown
Standardy inżynierskie projektu
===========================
1. Polecenia kompilacji i testowania:
- Kompilacja: npm run build
- Uruchamianie testów jednostkowych: npm test
- Linter: npm run lint
2. Zasady architektoniczne:
- Domyślnie używaj wyłącznie Server Components.
- Wszystkie typy przechowuj w katalogu src/types/.
- Nie stosuj typu any w kodzie TypeScript.
```
### Master-prompt do generowania idealnego Markdowna
```markdown
Działaj jako wiodący redaktor techniczny i ekspert ds. dokumentacji. Utwórz dokumentację techniczną zgodnie ze specyfikacją CommonMark / GFM.
Temat: [Podaj temat, np.: Architektura mikrousługi uwierzytelniania]
Wymagania dotyczące formatowania:
1. Nagłówki muszą być ścisłe od ## 1. do ## N. (Żaden # w treści dokumentu).
2. Zawsze stawiaj pojedynczą spację po znakach kratki (np. „## 1. Wstęp”, a nie „##1. Wstęp”).
3. Wszystkie fragmenty kodu umieszczaj w potrójnych backtickach z oznaczeniem języka (typescript, bash, json, mermaid).
4. Macierze porównawcze przedstawiaj w poprawnych tabelach GFM z wyrównaniem kolumn.
5. Dla ważnych ostrzeżeń używaj bloków callout (> [!NOTE], > [!WARNING]).
6. Linki zawierające spacje lub nawiasy muszą mieć URL zakodowany procentowo (%20, %28, %29).
Wygeneruj czysty, gotowy do publikacji dokument Markdown.
```
### Checklista kontroli jakości dokumentu Markdown
- [ ] W treści artykułu nie ma tagu `#` (H1 jest generowany wyłącznie z tytułu strony).
- [ ] Wszystkie sekcje najwyższego poziomu są ponumerowane kolejno (`## 1.`, `## 2.`).
- [ ] Po symbolach kratki `#` musi występować spacja.
- [ ] Wszystkie prompty, konfiguracje i przykłady kodu są owinięte w odpowiednie bloki ` ``` `.
- [ ] Znaki specjalne w linkach są zakodowane w formacie percent-encoding.
- [ ] Tabele są sformatowane zgodnie ze standardem GFM bez uszkodzonych separatorów.
- [ ] Teksty alternatywne (alt-text) dla obrazów są przetłumaczone i opisowe.