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

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.
Jednoznaczność semantyczna: Symbole #, -, > oraz backticki nie obciążają okna kontekstowego, dając modelowi wyraźną mapę hierarchii myśli.
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.
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.

Uwaga

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.

Hierarchia poziomów nagłówków w Markdownie i odpowiadające im tagi HTML Збільшити

Hierarchia poziomów nagłówków w Markdownie i odpowiadające im tagi HTML

Poziom nagłówka	Składnia Markdown	Ekwiwalent HTML	Typowe zastosowanie
Poziom 1	`# Nagłówek`	`<h1>`	Tytuł całego artykułu lub dokumentu (tylko 1 na stronę)
Poziom 2	`## Nagłówek`	`<h2>`	Główne sekcje i kluczowe moduły tematu
Poziom 3	`### Nagłówek`	`<h3>`	Podsekcje, kroki instrukcji, poszczególne narzędzia
Poziom 4	`#### Nagłówek`	`<h4>`	Szczegóły podpunktów, parametry, przypisy
Poziom 5	`##### Nagłówek`	`<h5>`	Drobne przypisy techniczne
Poziom 6	`###### Nagłówek`	`<h6>`	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.

Porównanie poprawnej i błędnej składni nagłówków Збільшити

Porównanie poprawnej i błędnej składni nagłówków

Ostrzeżenie

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 <h1>.

3. Formatowanie tekstu: pogrubienie, kursywa, przekreślenie i znaki specjalne

Formatowanie inline pomaga zwrócić uwagę na kluczowe terminy i pojęcia.

Składnia wyróżniania tekstu kursywą w Markdownie Збільшити

Składnia wyróżniania tekstu kursywą w Markdownie

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

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 ```bash npm run build

terminal

```

Uwaga

Upewnij się, że zmienne środowiskowe w pliku .env są poprawnie skonfigurowane przed uruchomieniem.

Sprawdź katalog wyjściowy dist/.

terminal

--- ## 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:** `<https://github.com>` lub `<support@example.com>` - **Obraz:** `[Opis obrazu dla dostępności](/images/diagram.webp "Podpowiedź")` - **Klikalny obraz-link:** `[![Alt-text](/images/btn.webp)](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): ![Prawidłowe kodowanie spacji i nawiasów okrągłych w linkach URL](/api/guides-media/automation/markdown-format-guide-for-ai/images/markdown-format-guide-for-ai-extra-03.webp) ```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})`; }

Ważne

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 (\).

Specjalne znaki składni Markdown, które można eskapować odwrotnym ukośnikiem Збільшити

Specjalne znaki składni Markdown, które można eskapować odwrotnym ukośnikiem

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 (<div>, <table>) 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.