Markdown został stworzony przez Johna Grubera w 2004 roku z jednym, eleganckim celem: pisać zwykły tekst, który czyta się naturalnie, a następnie konwertować go do czystego HTML. Dwie dekady później jest wszędzie — pliki README na GitHubie, opisy pull requestów, wiadomości na Slacku, dokumenty Notion, wpisy na blogu, odpowiedzi chatów AI. To jedno z tych narzędzi, których będziesz używać każdego dnia do końca swojej kariery, niezależnie od tego, czy myślisz o tym świadomie.

Czym właściwie jest Markdown

Markdown to zwykły tekst z lekką, czytelną składnią nałożoną na wierzchu. Znak # na początku linii staje się <h1>. Owinięcie słowa w **podwójne gwiazdki** pogrubia je. Cudzysłowy odwrócone tworzą wbudowany kod. Centralna filozofia projektowania mówi, że źródło Markdown powinno być czytelne takie jakie jest — nawet przed renderowaniem. Jeśli kiedykolwiek pisałeś e-mail z *gwiazdkami wokół akcentu* lub używałeś myślników dla listy wypunktowanej, pisałeś już coś bardzo zbliżonego do Markdown.

Oto szybkie porównanie przed i po. Markdown po lewej stronie produkuje HTML po prawej:

markdown
## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.
html
<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

Piszesz górną połowę; procesor Markdown produkuje dolną połowę. Ten krok translacji jest niewidoczny po skonfigurowaniu edytora lub potoku CI.

Podstawowa składnia — część wspólna dla każdego wariantu

Niezależnie od używanego wariantu Markdown, te elementy budulcowe działają wszędzie:

  • Nagłówki — # H1, ## H2, ### H3 (do sześciu poziomów)
  • Pogrubienie i kursywa — **pogrubienie**, *kursywa*, ***oba***
  • Linki — [tekst linku](https://url.com)
  • Obrazy — ![tekst alternatywny](obraz.png)
  • Kod wbudowany — `cudzysłów odwrócony` owijający fragment; potrojony cudzysłów odwrócony otwiera ogrodzony blok kodu
  • Cytaty blokowe — zacznij linię od >
  • Listy nieuporządkowane — linie zaczynające się od - lub *
  • Listy uporządkowane — linie zaczynające się od 1., 2. itd.
  • Pozioma linia — trzy lub więcej myślników: ---

Oto realistyczny fragment README, który używa wszystkich powyższych razem:

markdown
# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License
Wskazówka: możesz użyć naszego narzędzia Podgląd Markdown, aby wkleić dowolny Markdown i zobaczyć go renderowanego natychmiast — przydatne do sprawdzania składni przed wypchnięciem na GitHub.

Problem z wariantami — CommonMark, GFM i inne

Oto haczyk: „Markdown" to nie jedna rzecz. Oryginalna specyfikacja Grubera z 2004 roku była celowo luźna, co doprowadziło do lat niekompatybilnych implementacji. Różne parsery obsługiwały przypadki brzegowe — zagnieżdżone listy, puste linie wewnątrz cytatów blokowych, pierwszeństwo między akcentem a linkami — w różny sposób. Ten sam plik źródłowy renderował się inaczej w różnych narzędziach.

CommonMark (uruchomiony w 2014 roku) to naprawił. Grupa programistów — w tym osoby z GitHub, Stack Overflow i Reddit — napisała rygorystyczną, jednoznaczną specyfikację obejmującą każdy przypadek brzegowy zestawem testów 652 przykładów. Większość nowoczesnych narzędzi używa teraz CommonMark jako podstawy.

GitHub rozszerzył następnie CommonMark własnymi dodatkami i opublikował GitHub Flavored Markdown (GFM). GFM to to, co piszesz w plikach README, zgłoszeniach i pull requestach na GitHubie. Wiele innych narzędzi również przyjęło rozszerzenia GFM, ale nie wszystkie — więc to, co renderuje się na GitHubie, może renderować się inaczej w generatorze stron statycznych lub aplikacji do notatek. Wiedza, który wariant obsługuje Twoje narzędzie, oszczędza wiele drapania się po głowie.

Rozszerzenia GitHub Flavored Markdown

GFM dodaje pięć funkcji na szczycie CommonMark, których będziesz stale używać na GitHubie i w każdym narzędziu obsługującym nadzbiór GFM:

Tabele — kolumny rozdzielone pionową kreską z separatorem wiersza myślników:

markdown
| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

Listy zadań — pola wyboru w zgłoszeniach i pull requestach:

markdown
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

Przekreślenie — owiń tekst w podwójne tyldy:

markdown
~~deprecated API~~ — use `newMethod()` instead

Ogrodzone bloki kodu z podpowiedziami języka — identyfikator języka po otwierającym ogrodzeniu uruchamia podświetlanie składni:

markdown
```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

Automatyczne linki — gołe adresy URL, takie jak https://example.com, są automatycznie przekształcane w klikalne bez potrzeby używania składni [tekst](url). Jest to wygodne w komentarzach do zgłoszeń, ale może być zaskakujące, jeśli wkleisz URL, którego nie chcesz linkować.

Użyj naszego Formatera Markdown, aby wyczyścić niespójne odstępy, znormalizować wcięcia list i standaryzować ograniczniki ogrodzonych bloków kodu — przydatne przed zatwierdzaniem dokumentów do repozytorium.

Gdzie będziesz używać Markdown w praktyce

Markdown pojawia się w więcej miejscach niż większość programistów spodziewa się na początku:

  • GitHub i GitLab — pliki README, zgłoszenia, opisy pull requestów, wiki i nawet treści wiadomości commit. Każde repozytorium, do którego się dotkniesz, będzie miało co najmniej plik README.md.
  • Generatory stron statycznych — Jekyll, Hugo, Eleventy, Astro i Next.js akceptują pliki zawartości Markdown. Piszesz posty w plikach .md, a generator konwertuje je do stron HTML w czasie kompilacji.
  • Narzędzia dokumentacyjne — MkDocs, Docusaurus i GitBook są zbudowane całkowicie wokół źródła Markdown. Biblioteki open-source niemal powszechnie używają jednego z tych.
  • Aplikacje do notatek — Obsidian, Notion, Bear i Typora wszystkie używają Markdown jako natywnego formatu (z różnymi rozszerzeniami). Twoje notatki to przenośne pliki zwykłego tekstu, nie własnościowa baza danych.
  • Platformy CMS — Ghost używa Markdown natywnie. Contentful i Strapi obsługują pola Markdown. Bezgłowe konfiguracje CMS zazwyczaj przechowują długie treści jako ciągi Markdown.
  • Narzędzia AI — ChatGPT i Claude domyślnie generują Markdown. Fragmenty kodu, pogrubione terminy i listy wypunktowane w odpowiedziach AI to Markdown — interfejs czatu je renderuje, ale podstawowy tekst to **pogrubienie** i ```python.

Markdown kontra HTML — kiedy używać którego

Markdown konwertuje do HTML, ale nie może wyrazić wszystkiego, co potrafi HTML. Nie ma odpowiednika dla <div class="card">, atrybutów data-* lub atrybutów aria-*. W przypadku prostej treści prozaicznej — dokumentacji, plików README, wpisów na blogu, dzienników zmian — Markdown jest szybszy w pisaniu i znacznie bardziej czytelny w surowej formie. W przypadku złożonych komponentów UI, niestandardowych układów lub adnotacji dostępności wymagających konkretnych atrybutów potrzebujesz HTML.

Dobra wiadomość: większość procesorów Markdown przepuszcza surowy HTML bez zmian. Możesz mieszać oba podejścia. Jeśli potrzebujesz <figure> z <figcaption> lub widżetu ujawniającego <details>, po prostu napisz HTML bezpośrednio w pliku .md. Procesor przepuści go bez zmian. Używaj tej furtki oszczędnie — jeśli więcej niż jedna trzecia pliku to surowy HTML, równie dobrze możesz pisać HTML bezpośrednio i używać naszego Formatera HTML, aby go utrzymać w porządku.

  • Używaj Markdown do: dokumentacji, plików README, dzienników zmian, wpisów na blogu, artykułów bazy wiedzy, pól opisu API
  • Używaj HTML do: precyzyjnego układu, niestandardowych komponentów, formularzy, elementów wymagających konkretnych atrybutów
  • Mieszaj oba gdy: głównie proza z garstką wyjątków strukturalnych (responsywna tabela, osadzony film)

Podsumowanie

Markdown jest zwodniczo prosty — wygląda jak tylko garść zasad interpunkcyjnych, ale zasila dokumentację praktycznie każdego większego projektu open-source. Nauka podstawowej składni zajmuje około dziesięciu minut. Zrozumienie różnic między wariantami (CommonMark kontra GFM kontra to, czego używa Twój SSG) odróżnia programistów, którzy czasami walczą ze swoimi narzędziami do dokumentacji, od tych, którzy tego nie robią.

Autorytatywne referencje: CommonMark dla standaryzowanej specyfikacji, GitHub Flavored Markdown dla rozszerzeń GitHub i Markdown Guide dla praktycznej referencji ściągawki. Na co dzień nasz Podgląd Markdown pozwala zobaczyć renderowane wyjście natychmiast, a Formater Markdown utrzymuje pliki źródłowe w spójności.

← All Markdown articles Browse all categories →