Tabele w Markdown: składnia GFM, wyrównanie i ograniczenia
Tabele pipe w GFM, wyrównanie i limity komórek.
Tabela w Markdown to wiersz nagłówka, wiersz ogranicznika składający się z myślników oraz wiersze danych znajdujące się pod nimi. To właśnie wiersz ogranicznika sprawia, że znaczniki pipe tworzą tabelę w GFM oraz w Hugo.
Ten przewodnik jest częścią Narzędzia dokumentacyjne w 2026 roku: Markdown, LaTeX, PDF i procesy wydruku. Inne typy bloków znajdują się w Ściągawce Markdown.
Tabele nie są częścią oryginalnej składni Markdown ani standardu CommonMark. Są to rozszerzenie tabeli w specyfikacji GitHub Flavored Markdown. Hugo 0.164 używa Goldmarka z domyślnie włączonym tym rozszerzeniem (markup.goldmark.extensions.table). Poniższe przykłady są otoczone znakami kodu (fenced), aby znaki pipe pozostały dosłowne – jest to wzór opisany w artykule Bloki kodu w Markdown.
Składnia tabeli pipe
Tabela składa się z trzech części: jednego wiersza nagłówka, jednego wiersza ogranicznika oraz zera lub większej liczby wierszy danych. Komórki oddzielone są znakiem |. Pipe na początku i końcu wiersza są opcjonalne. Spacje obok pipe są usuwane (trimowane).
| Header 1 | Header 2 |
| --- | --- |
| Cell A1 | Cell B1 |
| Cell A2 | Cell B2 |
Dokumentacja pisarska GitHuba stwierdza, że każda komórka ogranicznika musi zawierać co najmniej trzy myślniki oraz że przed tabelą wymagana jest pusta linia, aby GitHub mógł ją wyrenderować. Specyfikacja GFM opisuje komórkę ogranicznika jako myślniki z opcjonalną dwukropkiem po jednej lub obu stronach, a jej przykłady zawierają komórkę z jednym myślnikiem. Hugo 0.164 wyrenderowało to jako tabelę:
| A | B |
| - | - |
| 1 | 2 |
Ten sam proces renderowania w Hugo zamienił tabelę na element <table>, gdy poprzednia linia była akapitem i nie było pustej linii. Na GitHubie należy przestrzegać ogranicznika z trzema myślnikami i pustej linii. Na tej stronie wystarcza jeden myślnik, a pusta linia nie jest wymagana.
|Too|Tight| z ogranicznikiem |---|---| również się wyrenderował. Spacje obok pipe są usuwane. Spacje w pierwszym przykładzie zapewniają czytelną czytelność różnic w źródle.
Wiersz nagłówka i wiersz ogranicznika muszą mieć tę samą liczbę komórek. Jeśli się różnią, Hugo nie rozpoznaje tabeli. Zawartość pozostaje zwykłym tekstem, a myślniki stają się wtedy podatne na działania typografa Hugo:
| abc | def |
| --- |
| bar |
Wiersz danych może być krótszy lub dłuższy niż nagłówek. Krótki wiersz jest uzupełniany pustymi komórkami. Komórki przekraczające liczbę z nagłówka są odrzucane.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
Pierwszy z tych przykładów wyświetla pustą trzecią komórkę. Drugi wyświetla tylko 1 i 2.
Linia bez pipe pozostaje wewnątrz tabeli do pustej linii. Hugo 0.164 wstawiło następujące bar do tabeli jako wiersz z pustą drugą komórką, zgodnie z przykładem 202 GFM. Następny akapit zaczyna się po pustej linii.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Wyrównanie kolumn
Wyrównanie ustawia się dwukropkiem w wierszu ogranicznika. --- bez dwukropka oznacza wyrównanie do lewej, tak samo jak :---.
| Left | Right | Center |
| :--- | ----: | :----: |
| text | 12.50 | yes |
| Left | Right | Center |
|---|---|---|
| text | 12.50 | yes |
Dwukropki w wierszu nagłówka to zwykłe znaki w tej komórce. Nie ustawiają one wyrównania. To wiersz ogranicznika poniżej był użyty przez Hugo:
| :--- Left | Right ---: |
| :-------- | ---------- |
| Correct | Alignment |
Zawartość komórek
Elementy inline działają wewnątrz komórki: pogrubienie, kursywa, fragmenty kodu i linki. Konstrukcje blokowe nie działają. Specyfikacja GFM mówi, że elementy poziomu blokowego nie mogą być wstawiane do tabeli, więc lista lub blok kodu wewnątrz komórki nie jest listą ani blokiem kodu.
| Feature | Status | Documentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Released* | [Docs](/api) |
| `Auth` | Beta | Coming soon |
Dosłowny znak pipe to \| lub |. Hugo 0.164 wyrenderowało oba jako |.
| Expression | Result |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Złamanie linii wewnątrz komórki to tag HTML <br>. Ta strona ustawia markup.goldmark.renderer.unsafe na true, więc ten tag jest zachowywany. Procesor, który usuwa surowy HTML, łączy te dwie połowy.
Trzy myślniki zapisane jako tekst komórki to osobna pułapka w Hugo. Typograf przepisuje --- w komórce na myślnik półpełski (—). Blok kodu (code span) zachowuje myślniki. \--- renderuje się jako -–.
| As text | As code |
| ------- | ------- |
| --- | `---` |
Złączone komórki
GFM nie ma atrybutów rowspan ani colspan. Gdy komórka musi obejmować dwa wiersze, tabela musi być zapisana w HTML. Niestandardowy renderer (unsafe renderer) tej strony pozostawia ten HTML w stronie:
<table>
<tr>
<td rowspan="2">Merged</td>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
</tr>
</table>
Generator markdown+pipe_tables w Pandoc emituje składnię pipe na tej stronie. To jest generator używany przy konwertowaniu dokumentów Word do Markdown. Tabele siatkowe (grid tables) i inne układy tylko Pandoc to cechy dialektu, opisane w GFM vs CommonMark vs Pandoc Markdown.
Szeroka tabela pipe przewija się lub wychodzi poza obszar. Przenośne redukcje to transponowany układ, kilka mniejszych tabeli lub tabela HTML z własnym CSS. Składnia pipe nie ma podpisu (caption). Spis treści Hugo jest budowany z nagłówków.
Sprawdzenia, gdy tabela pozostaje tekstem
Policz komórki w wierszu nagłówka i wierszu ogranicznika. Jeśli te dwie liczby się różnią, blok jest akapitem. Krótki wiersz danych to nadal tabela, z pustą komórką na końcu. Zasada markdownlint MD056 wymaga, aby każdy wiersz odpowiadał tej liczbie, ponieważ krótki wiersz wygląda jak brakująca komórka, a dodatkowa komórka jest odrzucana.
Sprawdź dwukropki w wierszu ogranicznika. Dwukropek znajdujący się w nagłówku to tekst, a kolumna pozostaje z wyrównaniem określonym w wierszu ogranicznika.
Jeśli --- wewnątrz komórki pojawia się na tej stronie jako pojedynczy znak myślnika, typograf go przepisał. Umieść myślniki w bloku kodu (code span).
Jeśli GitHub wyświetla znaki pipe jako tekst, dodaj pustą linię wymaganą w dokumentacji GitHuba i użyj co najmniej trzech myślników w każdej komórce ogranicznika. Hugo 0.164 już akceptowało krótszą formę.
Brakujący wiersz ogranicznika to inny sposób, w jaki blok pipe pozostaje tekstem. Hugo 0.164 pozostawiło to jako akapit:
| Header 1 | Header 2 |
| Cell A | Cell B |
Tabela parametrów
Ten sam wiersz ogranicznika niesie wyrównanie i zostawia miejsce na kod inline:
| Parameter | Type | Default | Required |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Yes |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
