W tym artykule
Czym są tabele Markdown?
Tabele Markdown używają znaków pionowej kreski (|) i myślników (-) do tworzenia ustrukturyzowanych danych tabelarycznych w dokumentach tekstowych. Są częścią GitHub Flavored Markdown (GFM) i są obsługiwane przez większość rendererów Markdown, w tym GitHub, GitLab, VS Code oraz generatory stron statycznych.
Tabele w Markdown są zaprojektowane do prostej prezentacji danych — nagłówki kolumn, wiersz separatora i wiersze danych. Renderują się jako właściwe tabele HTML w wyjściu, co czyni je idealnymi do dokumentacji, plików README i pisania technicznego bez znajomości HTML.
Składnia tabel Markdown
Tabela Markdown składa się z trzech części: wiersza nagłówka, wiersza separatora oraz jednego lub więcej wierszy danych.
- Wiersz nagłówka — pierwszy wiersz definiuje nazwy kolumn, oddzielone znakami pionowej kreski (|). Pionowe kreski na początku i końcu są opcjonalne, ale zalecane dla zachowania przejrzystości.
- Wiersz separatora — drugi wiersz używa myślników (---) między pionowymi kreskami, aby oddzielić nagłówek od danych. Wymagane są co najmniej trzy myślniki na kolumnę.
- Wiersze danych — każdy kolejny wiersz zawiera wartości komórek oddzielone pionowymi kreskami. Komórki nie muszą być wyrównane wizualnie, choć wyrównane kolumny poprawiają czytelność kodu źródłowego.
- Escaping pionowych kresek — jeśli zawartość komórki zawiera dosłowny znak pionowej kreski, poprzedź go ukośnikiem (\|), aby zapobiec interpretowaniu go jako separatora kolumn.
Opcje wyrównania kolumn
Wyrównanie kolumn jest kontrolowane przez dodanie dwukropków do wiersza separatora. To określa sposób wyrównania tekstu w każdej kolumnie.
- Wyrównanie do lewej (domyślne) — użyj :--- lub --- w separatorze. Tekst jest wyrównany do lewej krawędzi kolumny. Jest to domyślne ustawienie, gdy nie określono dwukropków.
- Wyrównanie do środka — użyj :---: w separatorze. Tekst jest wyśrodkowany w kolumnie. Przydatne dla etykiet statusu, kategorii lub krótkich wartości.
- Wyrównanie do prawej — użyj ---: w separatorze. Tekst jest wyrównany do prawej krawędzi. Idealne dla wartości liczbowych, cen, liczników i pomiarów.
Wypróbuj za darmo — bez rejestracji
Generuj tabele Markdown →Typowe przypadki użycia
Tabele Markdown są używane wszędzie tam, gdzie ustrukturyzowane dane muszą być prezentowane w dokumentacji.
- Dokumentacja README — tabele porównania funkcji projektu, wymagania instalacyjne, obsługiwane platformy oraz macierze zgodności wersji
- Dokumentacja API — odwołania do endpointów z metodą, ścieżką, opisem i tabelami parametrów dla każdej trasy
- Tabele porównawcze — porównania funkcji obok siebie, poziomy cenowe i oceny narzędzi w postach blogowych i recenzjach technicznych
- Dzienniki zmian — tabele historii wersji z datą, numerem wersji i opisem zmian dla każdego wydania
Wskazówki i najlepsze praktyki
Przestrzeganie tych wytycznych pomaga utrzymać tabele Markdown czytelne zarówno w formie źródłowej, jak i renderowanej.
- Utrzymuj wyrównanie kolumn w kodzie źródłowym — dopełniaj komórki spacjami, aby kolumny były wizualnie wyrównane. Większość edytorów i nasz generator obsługuje to automatycznie. Wyrównane źródło jest znacznie łatwiejsze do przeglądania w pull requestach.
- Unikaj złożonej zawartości w komórkach — tabele Markdown nie obsługują wieloliniowej zawartości komórek, elementów blokowych ani zagnieżdżonych tabel. Utrzymuj zawartość komórek krótką i prostą. W przypadku złożonych danych rozważ użycie tabel HTML.
- Ogranicz liczbę kolumn — tabele z więcej niż 5-6 kolumnami stają się trudne do odczytania na mniejszych ekranach. Rozważ podzielenie szerokich tabel na wiele skoncentrowanych tabel lub użycie innego formatu dla bardzo szerokich danych.
Często zadawane pytania
Czy istnieje ograniczenie zawartości komórek w tabelach Markdown?
Nie ma technicznego ograniczenia znaków dla zawartości komórek, ale komórki tabel Markdown są tylko jednolinijkowe. Nie można dołączać podziałów wierszy, akapitów ani elementów blokowych, takich jak listy, wewnątrz komórki. Dla złożonej zawartości komórek używaj tabel HTML z elementami <td>, które obsługują dowolną zawartość HTML.
Czy mogę scalać komórki w tabelach Markdown?
Nie. Standardowe tabele Markdown nie obsługują colspan ani rowspan — każdy wiersz musi mieć tę samą liczbę kolumn. Scalanie komórek wymaga tabel HTML. Jeśli potrzebujesz scalonych komórek, napisz tabelę w HTML i osadź ją bezpośrednio w dokumencie Markdown.
Czy mogę zagnieżdżać tabele wewnątrz tabel Markdown?
Nie. Tabele Markdown nie mogą być zagnieżdżane. Każda tabela to płaska siatka wierszy i kolumn. Jeśli potrzebujesz danych hierarchicznych, rozważ użycie zagnieżdżonych list, osobnych tabel z nagłówkami lub tabel HTML z zagnieżdżonymi elementami <table>.