Wypróbuj składnię

Odniesienie składni

Czym jest składnia Markdown?

Markdown to lekki język znaczników stworzony przez Johna Grubera w 2004 roku. Używa prostych symboli i znaków do formatowania tekstu, ułatwiając pisanie treści konwertowanych do HTML bez wyglądu chaotycznego w surowej postaci. Markdown stał się standardem dla dokumentacji, plików README, blogów i wszelkich treści wymagających prostego, czytelnego formatowania.

CommonMark to najszerzej akceptowana specyfikacja Markdown, która definiuje sposób interpretowania składni przez parsery. Ucząc się składni kompatybilnej z CommonMark, twoje treści będą renderowane spójnie na GitHub, GitLab, Discord, Slack, Reddit, Stack Overflow i dziesiątkach innych platform. Oryginalna specyfikacja Markdown Johna Grubera pozostaje fundamentalna, podczas gdy rozszerzenia jak GitHub Flavored Markdown dodają funkcje takie jak listy zadań, przekreślony tekst i tabele.

Nowoczesny Markdown jest dostępny w wielu wariantach dostosowanych do konkretnych platform. GitHub Flavored Markdown (GFM) dodaje tabele, pola wyboru i autolinki. GitLab Markdown obsługuje podobne rozszerzenia plus diagramy. Nauka podstawowej składni CommonMark zapewnia przenośną bazę działającą wszędzie.

Jak używać Przewodnika po składni Markdown

Wykonaj te kroki, aby nauczyć się i wypróbować składnię Markdown.

Wklej, prześlij lub załaduj przykład

Wklej Markdown do lewego panelu Wypróbuj składnię lub kliknij Prześlij, aby załadować plik .md. Kliknij Przykład dla przykładowej dokumentacji. Prawy panel Odniesienie składni pokazuje wzorce CommonMark i GFM.

Ćwicz i korzystaj z odniesienia

Używaj odniesienia dla nagłówków, nacisku, list, linków, tabel, bloków kodu. Kopiuj przykłady do lewego panelu, aby je wypróbować. Obejmuje CommonMark plus rozszerzenia GitHub Flavored Markdown.

Kopiuj lub pobierz

Kliknij Kopiuj lub Pobierz, aby zapisać odniesienie. Użyj Wyczyść, aby zacząć od nowa. Całe przetwarzanie odbywa się w przeglądarce.

Kiedy naprawdę by się przydało

Pisanie dokumentacji

Dokumentacja techniczna, przewodniki referencyjne API i dokumentacja oprogramowania są pisane prawie powszechnie w Markdown. Python Docs, przewodniki Node.js i większość projektów open source używa Markdown dla swoich stron dokumentacji. Odniesienie do składni pozwala ci pozostać produktywnym podczas pisania złożonej dokumentacji.

README'y i pliki projektu

Każdy projekt GitHub ma plik README.md opisujący projekt, użycie, instalację i wytyczne dotyczące wkładu. Te pliki są całkowicie napisane w Markdown i często są pierwszą rzeczą, którą widzą użytkownicy.

Tworzenie i publikowanie treści

Platformy blogowe jak Jekyll, Hugo i Ghost akceptują Markdown dla treści. Platformy w stylu Medium i generatory stron statycznych używają Markdown jako głównego formatu wejściowego. Znajomość składni pomaga pisać szybciej i utrzymywać spójne formatowanie.

Komunikacja współpracy

Slack, Discord, issues GitHub, komentarze do pull requestów i wpisy na forach obsługują formatowanie Markdown. Podczas przeglądów kodu, zgłaszania błędów lub rozmów w zespołach, Markdown pozwala jasno sformatować wiadomość bez przerywania przepływu rozmowy.

Często zadawane pytania (FAQ)

Czy mogę używać HTML wewnątrz Markdown?

Tak, Markdown pozwala na mieszanie surowego HTML. Jeśli Markdown nie obsługuje czegoś, czego potrzebujesz, możesz napisać HTML bezpośrednio i zostanie on przekazany do wyjścia. Zgodnie ze specyfikacją CommonMark, bloki HTML i inline HTML są rozpoznawane i przekazywane bez zmian. Używaj oszczędnie.

Jaka jest różnica między gwiazdkami a podkreśleniami dla nacisku?

Funkcjonalnie są identyczne w CommonMark — *tekst* i _tekst_ oba produkują kursywę, **tekst** i __tekst__ oba produkują pogrubienie. Wybór jest stylistyczny. Wiele zespołów woli gwiazdki dla spójności i ponieważ są łatwiejsze do wpisania na większości klawiatur.

Jak działają podziały wierszy w Markdown?

To częste źródło zamieszania. Pojedynczy powrót karetki w źródle jest traktowany jako spacja. Aby utworzyć prawdziwy podział wiersza (<br> w HTML), dodaj dwie spacje na końcu wiersza przed naciśnięciem Enter lub użyj ukośnika odwrotnego przed powrotem karetki. Do podziałów akapitu użyj pustego wiersza.

Czy tabele są obsługiwane wszędzie w Markdown?

Nie. Tabele są częścią GitHub Flavored Markdown i innych rozszerzeń, ale nie standardu CommonMark. Większość nowoczesnych platform (GitHub, GitLab, Discord) je obsługuje, ale niektóre starsze parsery Markdown nie rozpoznają składni potokowej.

Jak escape'ować znaki specjalne?

Użyj ukośnika odwrotnego (\) przed znakami o specjalnym znaczeniu w Markdown: ukośnik odwrotny (\), backtick (`), gwiazdka (*), podkreślenie (_), klamry ({}), nawiasy kwadratowe ([]), nawiasy okrągłe (()), krzyżyk (#), plus (+), minus (-), kropka (.) i wykrzyknik (!). Na przykład \*nie kursywa\* renderuje gwiazdki dosłownie.

Jaki jest najlepszy sposób formatowania kodu w Markdown?

Do kodu inline używaj pojedynczych backtick'ów: `kod tutaj`. Do bloków kodu używaj potrójnych backtick'ów z opcjonalnym tagiem języka (```javascript) dla podświetlania składni. Unikaj wcięcia kodu jako bloku kodu — bloki z ogrodzeniem są wyraźniejsze i bardziej przenośne.

Przewodnik po składni Markdown