Ściąga Markdown

Ściąga Markdown z podglądem na żywo (GitHub + CommonMark) | We.Inc

Każdy element Markdown z przykładem, który możesz edytować i od razu zobaczyć wyrenderowany: łamanie linii, linki, tabele, checkboxy, przypisy, bloki kodu i alerty GitHub, a do tego szablon README.

Ściąga Markdown

Markdown formatuje zwykły tekst kilkoma symbolami: # dla nagłówków, **dwie gwiazdki** dla pogrubienia, [tekst](adres) dla linków, - dla list punktowanych i trzy backticki dla bloków kodu. Każdy przykład poniżej można edytować, a podgląd obok aktualizuje się podczas pisania, więc możesz przetestować składnię, zanim jej użyjesz.

Pięć elementów, których użyjesz najczęściej

Chcesz
Wpisz

Nagłówek

Pogrubienie
**important**

Link
[label](https://example.com)

Lista punktowana
- item

Nowa linia
dwie spacje na końcu linii

Osiemnaście przykładów na żywo obejmujących wszystko od nagłówków po przypisy i alerty GitHub, tabela różnic między GitHub a standardowym CommonMark, szablon README i pełny edytor na dole strony.

Znajdź potrzebny element. Etykieta pod każdym przykładem mówi, czy działa wszędzie, na GitHub i w większości aplikacji, czy tylko na GitHub.
Edytuj Markdown w lewym polu. Podgląd po prawej renderuje go podczas pisania.
Użyj Resetuj, aby przywrócić oryginalny przykład, i Kopiuj, aby zabrać Markdown ze sobą.
Przy dłuższych tekstach użyj pełnego edytora na dole albo wczytaj do niego szablon README.

Zostawiaj pustą linię przed i po listach, tabelach, blokach kodu i nagłówkach. Wiele rendererów jej wymaga, a nigdy nie szkodzi.
Pisz tekst alternatywny dla każdego obrazu. To właśnie słyszą użytkownicy czytników ekranu i to się wyświetla, gdy obraz się nie załaduje.
W długich dokumentach używaj linków referencyjnych. Tekst pozostaje czytelny, a każdy adres jest zapisany tylko raz.
Jeśli coś renderuje się jako zwykły tekst, sprawdź, czy nie brakuje spacji: #Heading i -item nie są rozpoznawane, a # Heading i - item tak.

Najczęściej zadawane pytania

Jak zrobić łamanie linii w Markdown?

Zakończ linię dwiema spacjami lub backslashem, a potem naciśnij Enter. Zwykły Enter jest traktowany jak spacja i linie się łączą. Aby zamiast łamania linii zacząć nowy akapit, zostaw jedną pustą linię.

Jak dodać checkbox w Markdown?

Zacznij element listy od - [ ] dla pustego pola lub - [x] dla zaznaczonego. Listy zadań są częścią GitHub Flavored Markdown, więc działają na GitHub, GitLab i w większości aplikacji do notatek, ale nie w ścisłym CommonMark.

Jak zrobić tabelę?

Napisz wiersz nagłówka z pionowymi kreskami między kolumnami, potem wiersz myślników, a potem po jednej linii na każdy wiersz. Kolumny w źródle nie muszą być wyrównane. Dodaj dwukropki w wierszu myślników, aby wyrównać kolumnę do lewej, do prawej lub do środka.

Czym różnią się Markdown, CommonMark i GFM?

Markdown to oryginalna składnia z 2004 roku, która wiele przypadków pozostawiła niezdefiniowanych. CommonMark to precyzyjna specyfikacja tej podstawowej składni. GitHub Flavored Markdown to CommonMark plus tabele, listy zadań, przekreślenie, automatyczne linki i przypisy i to właśnie za nim podąża większość narzędzi deweloperskich.

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

Większość rendererów na to pozwala, więc znaczniki details i summary albo wyśrodkowany obraz są w README częste. GitHub ze względów bezpieczeństwa usuwa skrypty, style i niektóre atrybuty. Podglądy na tej stronie nie renderują surowego HTML, więc pokazują go jako tekst.

Dlaczego Markdown wygląda inaczej w różnych aplikacjach

Oryginalny opis Markdown pozostawił otwartych wiele przypadków brzegowych, na przykład jak głęboko trzeba wciąć zagnieżdżoną listę albo czy łamanie linii wymaga dwóch spacji. Każda aplikacja dokonała własnych wyborów. CommonMark ustalił te reguły w specyfikacji i większość nowoczesnych narzędzi się jej trzyma, dodając na wierzchu własne rozszerzenia.
Dlatego etykieta wsparcia ma znaczenie. Nagłówki, wyróżnienia, linki, listy, cytaty i kod działają wszędzie. Tabele, checkboxy, przekreślenie i przypisy pochodzą z rozszerzeń GitHub i działają w większości miejsc, ale nie we wszystkich. Alerty są wyłącznie GitHubowe.

Jak napisać dobre README

README to strona główna projektu. Zacznij od jednego zdania o tym, co projekt robi i dla kogo jest, potem pokaż instalację i uruchomienie w bloku kodu do skopiowania, a następnie najmniejszy użyteczny przykład. Długie materiały referencyjne umieść w osobnych plikach i podlinkuj je.
Szablon poniżej trzyma się tej kolejności. Wczytaj go do edytora, zastąp tekst zastępczy i skopiuj wynik do README.md.

Nagłówki

Od jednego do sześciu znaków #, potem spacja. Używaj jednego nagłówka # na dokument.

Pogrubienie i kursywa

Podkreślniki (__bold__, _italic_) też działają, ale nie w środku słowa.

Przekreślenie

Dwie tyldy z każdej strony. Część GitHub Flavored Markdown, nie podstawowego CommonMark.

Łamanie linii

Pojedynczy Enter nie łamie linii. Zakończ ją dwiema spacjami lub backslashem albo zostaw pustą linię, aby zacząć nowy akapit.

Linki

Tekst w nawiasach kwadratowych, adres w okrągłych. Nawiasy ostre sprawiają, że goły adres staje się klikalny.

Linki referencyjne

Usuwają długie adresy z tekstu. Definicje mogą być w dowolnym miejscu i nie są wyświetlane.

Obrazy

Jak link, ale z ! na początku. Tekst w nawiasach to tekst alternatywny odczytywany przez czytniki ekranu.

Listy

Użyj -, * lub + dla punktów i 1. dla numeracji. Wcięcie o dwie do czterech spacji tworzy zagnieżdżenie.

Checkboxy (listy zadań)

Spacja między nawiasami oznacza niezaznaczone pole; x oznacza zaznaczone. Na GitHub możesz je zaznaczać w issues.

Cytaty blokowe

Zacznij każdą linię od >. Linia zawierająca tylko > utrzymuje akapity w jednym cytacie.

Kod w linii

Backticki zachowują tekst dokładnie tak, jak go wpisano. Aby pokazać backtick, otocz tekst dwoma: `` a`b ``.

Bloki kodu

Trzy backticki przed i po. Słowo po otwierającym ogrodzeniu określa język do podświetlania składni.

Tabele

Pionowe kreski oddzielają kolumny; wiersz myślników jest wymagany. Dwukropki ustawiają wyrównanie: do lewej, do prawej lub do środka.

Linia pozioma

Trzy lub więcej myślników, gwiazdek lub podkreślników w osobnej linii. Zostaw puste linie wokół myślników, aby nie zostały odczytane jako podkreślenie nagłówka.

Przypisy

Przypis trafia na dół dokumentu z linkiem powrotnym.

Escapowanie znaków

Backslash przed * _ # [ ] ` i podobnymi znakami wyświetla je jako zwykły tekst.

Automatyczne linki

GitHub zamienia zwykłe adresy w linki. Ścisły CommonMark wymaga nawiasów ostrych.

Alerty (wyróżnione bloki)

GitHub pokazuje je jako kolorowe ramki; inne aplikacje pokazują zwykły cytat, tak jak podgląd tutaj.

Składnia Markdown i gdzie działa

Element
Markdown
Działa w

Czym GitHub Flavored Markdown różni się od CommonMark

Funkcja
CommonMark
GitHub (GFM)

Tabele
Nieobsługiwane
Obsługiwane

Checkboxy list zadań
Nieobsługiwane
Obsługiwane, klikalne w issues i pull requestach

Przekreślenie
Nieobsługiwane
~~text~~

Gołe adresy URL stają się linkami
Tylko w <nawiasach ostrych>
Tak, dla adresów http, https i www

Przypisy
Nieobsługiwane
Obsługiwane

Alerty takie jak > [!NOTE]
Zwykły cytat blokowy
Ostylowana ramka z wyróżnieniem

Surowy HTML
Dozwolony
Dozwolony, ale skrypty, style i niektóre znaczniki są usuwane

Wzmianki i linki do issues
Zwykły tekst
@user i #123 stają się linkami

Wszędzie

GitHub i większość aplikacji

Tylko GitHub

Markdown (edytuj mnie)

Podgląd

Kopiuj

Resetuj

Składnia w skrócie

Każdy element na żywo

GitHub a CommonMark

Szablon README

Kopiuj szablon

Otwórz w edytorze

Pełny edytor

Markdown

Kopiuj Markdown

{n} słów. Nic nie jest zapisywane ani wysyłane.

Zacznij za darmo · Bez karty kredytowej

Powiązane: Poradniki

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony