Przewodnik po Markdown

Czym jest Markdown?

Markdown to lekki język znaczników, którego możesz używać do dodawania elementów formatowania do dokumentów tekstowych w postaci zwykłego tekstu. Pozwala tworzyć sformatowany tekst za pomocą prostej, łatwej do czytania składni, która może być konwertowana do HTML i innych formatów.

Pomyśl o Markdown jako o sposobie pisania sformatowanych dokumentów bez potrzeby używania skomplikowanych procesorów tekstu. Wystarczy dodać specjalne znaki do zwykłego tekstu, aby wskazać formatowanie jak pogrubienie, kursywa lub kod.

Dlaczego używać Markdown?

Markdown jest niezwykle prosty i łatwy do nauki. Możesz opanować podstawy w zaledwie 10 minut. Symbole formatowania są intuicyjne - gwiazdki do podkreślenia, kratki do nagłówków. Po prostu piszesz i dodajesz proste symbole, aby sformatować swój tekst.

Markdown działa na każdej platformie i w każdym edytorze tekstu. Ponieważ pliki to zwykły tekst, zawsze będą czytelne, nawet za dziesięciolecia. Pliki są lekkie i ładują się szybko.

Markdown ma szerokie wsparcie na różnych platformach. GitHub, Reddit, Discord i Slack używają Markdown. Popularne aplikacje jak Obsidian, Notion i VS Code obsługują go natywnie. To czyni go idealnym do dokumentacji, robienia notatek i treści internetowych.

Markdown działa doskonale z systemami kontroli wersji jak Git. Możesz skupić się na treści bez rozpraszania formatowaniem. Współpraca zespołowa jest łatwiejsza, ponieważ każdy może edytować pliki bez specjalnego oprogramowania.

Historia rozwoju Markdown

Początek: Waniliowy Markdown (2004)

Markdown został pierwotnie stworzony przez Johna Grubera w 2004 roku, ze znaczącym wkładem Aarona Swartza. Gruber zaprojektował go jako prosty sposób pisania używając łatwy do czytania i pisania format zwykłego tekstu, który mógł być konwertowany do strukturalnie poprawnego HTML. To jest "rdzeń", który John Gruber początkowo zaprojektował i zaimplementował, zawierający najbardziej podstawową składnię formatowania - to, co nazywamy "podstawowym waniliowym smakiem".

Podstawowa składnia (Waniliowy Markdown zawiera):

  • •
    Nagłówki: Użyj symbolu # (# Nagłówek)

  • •
    Podkreślenie:

  • •
    Kursywa: Użyj * lub _ aby otoczyć tekst (*kursywa* lub _kursywa_)
  • •
    Pogrubienie: Użyj ** lub __ aby otoczyć tekst (**pogrubienie** lub __pogrubienie__)

  • •
    Listy:

  • •
    Listy nieuporządkowane: Użyj *, -, lub + (- element)
  • •
    Listy uporządkowane: Użyj liczb z kropkami (1. element)
  • •
    Linki: Użyj [tekst linku](adres linku)
  • •
    Obrazy: Użyj ![opis obrazu](adres obrazu)

  • •
    Bloki kodu: Wcięcie spacjami (zwykle 4 spacje lub 1 Tab)

  • •
    Cytaty: Użyj symbolu > (> To jest cytat)
  • •
    Linie poziome: Użyj --- lub ***

Problem: Niespójne implementacje

Jednak Waniliowy Markdown nie miał ścisłej, formalnej specyfikacji. To prowadziło do niespójnego zachowania w różnych parserach Markdown przy obsłudze przypadków granicznych.

Obsługa białych znaków: Na przykład, w elementach listy, ile spacji wcięcia liczy się jako podlista? Czy to 2 spacje, 3 spacje, czy 4 spacje? Różne parsery mogły mieć różne oceny.

Przetwarzanie łamania linii: W określonych sytuacjach, czy zwykłe łamanie linii(\n) powinno być parsowane jako tag <br> (łamanie linii), czy powinno być po prostu traktowane jako spacja w tekście? To również może się różnić w zależności od parsera.

Mieszane użycie HTML: Markdown pozwala na osadzony HTML. Jednak w niektórych złożonych strukturach HTML, jak parsery Markdown obsługują składnię Markdown w nich, również przedstawia dwuznaczne obszary.

Rozwiązanie: CommonMark (2014)

We wrześniu 2014 roku wprowadzono CommonMark, aby rozwiązać te problemy niespójności. Kierowany przez Johna MacFarlane'a, zapewnia rygorystyczną specyfikację dla Markdown.

CommonMark zapewnia precyzyjną specyfikację, gdzie każdy przypadek graniczny jest jasno zdefiniowany. Zawiera kompleksowy zestaw testów z ponad 600 przypadkami testowymi, aby zapewnić spójność między implementacjami. Specyfikacja zapewnia referencyjną implementację, która służy jako standard dla innych parserów do naśladowania. Utrzymuje zgodność wsteczną z większością istniejących dokumentów Markdown, zapewniając jednocześnie jednoznaczne parsowanie, gdzie te same dane wejściowe zawsze produkują te same dane wyjściowe we wszystkich zgodnych parserach.

Rozszerzone smaki i dodatkowe funkcje

Gdy użytkownicy mieli różne potrzeby, pojawiły się różne rozszerzone smaki Markdown, aby sprostać określonym wymaganiom.

Dodatkowa składnia GitHub Flavored Markdown (GFM):

  • •
    Tabele: Użyj składni rur do tworzenia tabel
  | Nagłówek 1 | Nagłówek 2 | Nagłówek 3 |
  |------------|------------|------------|
  | Komórka 1  | Komórka 2  | Komórka 3  |
  | Komórka 4  | Komórka 5  | Komórka 6  |
  • •
    Przekreślenie: Użyj ~~ aby otoczyć tekst (~~usunięty tekst~~)

  • •
    Listy zadań: Twórz interaktywne pola wyboru

  - [x] Ukończone zadanie
  - [ ] Nieukończone zadanie
  • •
    Ogrodzone bloki kodu: Użyj potrójnych znaczników wstecznych ze specyfikacją języka
  ```javascript
  function hello() {
    console.log("Hello World!");
  }
  ```
  • •
    Automatyczne linkowanie: URLe i adresy email stają się klikalne automatycznie

Inne popularne rozszerzenia:

  • •
    Przypisy: Użyj składni [^1] do pisania akademickiego
  To jest zdanie z przypisem[^1].
  [^1]: To jest treść przypisu.

Wynik: To jest zdanie z przypisem¹.

  • •
    Wyrażenia matematyczne: Użyj $E=mc^2$ do dokumentów naukowych
  • •
    Skróty emoji: Użyj :smile: staje się 😊

  • •
    Listy definicji: Do słowników i dokumentacji technicznej

  Termin 1
  : Definicja dla terminu 1
  
  Termin 2
  : Definicja dla terminu 2
  : Inna definicja dla terminu 2

Wynik: Tworzy sformatowane listy z podświetlonymi terminami i wciętymi definicjami

Jak to działa?

Markdown podąża za prostym trzystopniowym przepływem pracy:

Krok 1: Utwórz plik Markdown

Najpierw tworzysz plik zwykłego tekstu z rozszerzeniem .md lub .markdown używając dowolnego edytora tekstu. Piszesz swoją treść używając prostych symboli formatowania:

Krok 2: Przetwórz narzędziami Markdown

Twój plik .md jest następnie przetwarzany przez narzędzia konwersji Markdown lub procesory. Te narzędzia czytają twój plik Markdown i konwertują go do żądanego formatu wyjściowego.

Krok 3: Wyjście do różnych formatów

Procesor Markdown może konwertować twój plik do wielu formatów:

Do wyświetlania w sieci:

  • •
    Konwertuje do HTML dla stron internetowych, blogów i aplikacji webowych

  • •
    Wyświetla sformatowaną treść w przeglądarkach z odpowiednim stylem

Do dokumentów:

  • •
    Konwertuje do PDF dla dokumentów do druku i raportów

  • •
    Generuje dokumenty Word (.docx) do użytku biurowego
  • •
    Tworzy LaTeX do prac akademickich i publikacji

Do publikowania:

  • •
    Generuje e-booki (format EPUB)

  • •
    Tworzy slajdy prezentacji
  • •
    Produkuje strony dokumentacji

Ten przepływ pracy oznacza, że piszesz raz w Markdown, a następnie używasz różnych narzędzi do konwertowania swojej treści do dowolnego formatu, którego potrzebujesz - czy to wyświetlanie na stronie internetowej, drukowanie jako PDF, czy udostępnianie jako dokument.

Dodatkowe zasoby

Podstawowa dokumentacja

  • •
    Dokumentacja Markdown Johna Grubera : Oryginalny przewodnik napisany przez twórcę Markdown. Podstawowa lektura do zrozumienia filozofii i podstawowej składni.

  • •
    Wikipedia - Markdown : Kompleksowy przegląd historii Markdown, wariacji i szczegółów technicznych.

  • •
    Przewodnik po Markdown : Kompleksowy przewodnik przyjazny dla początkujących z przykładami i najlepszymi praktykami dla wszystkich poziomów umiejętności.