Markdown - poradnik



  • Spis teści:

    Wstęp

    NodeBB, inaczej niż phpBB, grupy Jeja i wiele innych rodzajów forów, nie korzysta z BBCode, a z Markdowna.
    Jest to język znaczników nawet prostszy od BBCode, operujący na rzadko używanych symbolach specjalnych zamiast tagach podobnych do html.
    Więc choć pewnie wiele osób przyzwyczajonych do starego standardu będzie dalej z niego korzystało - na co zresztą to forum pozwala, akceptując podstawowe tagi BBCode - to moim zdaniem warto się nauczyć Markdowna. Tym bardziej, że można go już spotkać w wielu miejscach internetu (np. Discord, Reddit, GitHub) i ilość używających tego standardu stron pewnie się zwiększy.
    Markdown ma jednak jeden problem - mimo tego jak się do niego wcześniej odnosiłem, nie jest to jeden standard, a cała masa standardów opierających się o takie same podstawy. Ten post ma więc przybliżyć wersję Markdowna używaną na tym forum.

    Akapity

    W Markdownie istnieje jeden bardzo ważny koncept nie znajdujący się w BBCode: podział dokumentu na akapity.
    Dlaczego jest to takie ważne? Niektóre tagi dotyczą bowiem akapitu. Przykładem może być tu wyrównanie tekstu, albo cytaty.

    Czym więc jest akapit w Markdownie? Jest to dowolny blok tekstu oddzielony od innych pustą linią. “Pustą” oznacza tu, że nie ma w tej linii żadnego widocznego znaku - mogą być tam choćby spacje, tabulatory itp.
    Ta linia więc jest częścią tego samego akapitu co poprzednia, mimo że oddzielona jest jednym enterem.

    Gdy więc potrzeba nowego akapitu, najprostszym sposobem na stworzenie go jest naciśnięcie entera dwa razy - i już.

    To nie jest ten sam akapit co poprzedni.

    Podstawowe formatowanie

    Dobrze, ale jak robić to na co pozwalał BBCode? Co z [b]pogrubieniem[/b], czy [i]pochyleniem[/i] tekstu i całą masą innych rzeczy? Podstawy są bardzo proste:

    • **pogrubiny tekst**
      • pogrubiony tekst
    • lub __pogrubiony tekst__
      • pogrubiony tekst
    • *pochylony tekst*
      • pochylony tekst
    • lub _pochylony tekst_
      • pochylony tekst
    • ~~przekreślony tekst~~
      • przekreślony tekst

    Łatwe, prawda? Szczególnie, że pogrubienie i pochylenie da się osiągnąć na dwa sposoby.

    Ale jak wspomniałem BBCode też działa z podstawowymi tagami, więc mogę pogrubić lub pochylić tekst bez Markdowna - wystarczy zwykłe [b] i [i].

    Linki i obrazy

    A co z linkami? Oczywiście, stworzą się automatycznie gdy się po prostu wstawi cały link, ale jak dać im tekst tak jak przy [url] z BBCode? Jest to na szczęście praktycznie tylko zmiana symboli i kolejności:
    [tekst](url)
    Na przykład:
    [o taki link](https://wieloswiat.pl) da nam o taki link

    Praktycznie identycznie dodaje się obrazy, dodając tylko wykrzyknik:
    ![tekst alternatywny](url obrazu)
    Na przykład:
    ![Przykład](https://wieloswiat.pl/assets/uploads/example.png) da nam
    Przykład

    Tekst alternatywny nie jest oczywiście potrzebny (można napisać ![](url), ale miło mieć opcję dodania go)

    Nagłówki

    Można korzystać z kilku poziomów nagłówków (do 6). Dodaje się je tak:

    • # nagłówek 1 poziomu
      • nagłówek 1 poziomu

    • ## nagłówek 2 poziomu
      • nagłówek 2 poziomu

    • ### nagłówek 3 poziomu
      • nagłówek 3 poziomu

    • #### nagłówek 4 poziomu
      • nagłówek 4 poziomu

    • ##### nagłówek 5 poziomu
      • nagłówek 5 poziomu
    • ###### nagłówek 6 poziomu
      • nagłówek 6 poziomu

    Nagłówki 1 i 2 poziomu można jednak dodać w inny sposób:

    Umieszczając kilka znaków równości pod akapitem dla 1 poziomu
    ===

    O tak

    Albo kilka minusów dla 2 poziomu
    ---

    O tak

    Dodatkowo warto dodać, że istnieje możliwość linkowania do nagłówków. Robi się to po prostu jako link dając #tekst-naglowka - przy czym w linku tekst musi być pisany małymi literami i z - zamiast spacji.
    Np. [nagłówek 1 poziomu](#nagłówek-1-poziomu) da nam nagłówek 1 poziomu

    Listy

    Markdown pozwala też na łatwe tworzenie list z punktorami.
    Wystarczy w zasadzie zacząć pisać listy jak normalnie:
    * pierwszy element
    * drugi element
    Czyli

    • pierwszy element
    • drugi element

    Albo
    - pierwszy element
    - drugi element
    - pierwszy element
    - drugi element

    Działa też z cyframi:
    \1. pierwszy element
    \2. drugi element

    1. pierwszy element
    2. drugi element

    Jeden element listy kończy albo rozpoczęcie kolejnego, albo koniec akapitu (czyli odstęp jednego entera).

    Warto też dodać, że można tworzyć kilka stopni list, dodając przynajmniej 2 spacje na każdy kolejny stopień przed tagiem rozpoczynającym kolejny element. Na przykład:
    * Pierwszy stopień
      * Drugi stopień
        * Trzeci stopień
      * Dalej drugi stopień
    * Znowu pierwszy
    Da nam:

    • Pierwszy stopień
      • Drugi stopień
        • Trzeci stopień
      • Dalej drugi stopień
    • Znowu pierwszy

    Działa też z cyframi

    1. Pierwszy stopień
      1. Drugi stopień
        1. Trzeci stopień
      2. Znowu drugi stopień
    2. I znowu pierwszy

    Można też spokojnie mieszać rodzaje:

    • Element z punktorem
      1. i podpunkt numeryczny
      • a także taki z punktorem

    Kolory

    Choć zwykle lepiej jest trzymać się jednego koloru tekstu, to czasami można coś podkreślić przez zmienienie jego koloru. Jak więc to zrobić?
    %(#hex koloru)[kolorowy tekst]
    Czyli na przykład:
    %(#F​​F000​0)[czerwony] da nam czerwony

    Czym jest hex koloru? Jest to 6 cyfrowy (w systemie 16 - dlatego hex, od hexadecimal) kod opisujący kolory jako ilość czerwonego, zielonego i niebieskiego (od 00 do FF, czyli 255). Na przykład #FF0000 oznacza wartość 255 dla czerwonego, 00 dla zielonego i 00 dla niebieskiego, czyli po prostu czerwony, a #00FF00 da nam zielony.
    Można też je oczywiście mieszać, więc #FF00FF da nam fioletowy, a #F2FF02 odcień żółtego.

    Na szczęście nie trzeba niczego robić manualnie, bo istnieje w internecie masa stron pozwalających znaleźć kod potrzebnego koloru - nawet google ma selektor kolorów dający wartości hex. Wystarczy wyszukać jakiś kolor w hex, albo sam “selektor kolorów”
    Nie trzeba jednak nawet wychodzić poza Wieloświat, bo w edytorze też jest selektor (pod ikoną pipety) dający od razu cały markdown, w którym trzeba tylko wpisać tekst.

    Spoilery

    Drobna i prost funkcja: spoilery w tekście, czyli po prostu jego ukryty fragment.
    Tak jak proste jest ich działanie, tak proste jest korzystanie z nich:

    ||jakiś tekst||

    Da nam:

    jakiś tekst

    Jedną rzeczą którą jednak trzeba pamiętać ze spoilerami jest to, że muszą być oddzielnym akapitem - rozdzielone od reszty tekstu enterem z obu stron. Bez tego niestety nie działają (postaram się to w przyszłości naprawić, ale jest to bardzo małym priorytetem)

    Wyrównywanie tekstu

    Poza standardowym wyrównaniem do lewej, można tu też wyrównać tekst inaczej: do środka i do prawej.

    Podstawowe wyrównanie tworzy się dodając po prostu |- (na początku akapitu; do lewej) i -​| (na końcu; do prawej)
    Tak więc

    ​|-Takie coś
    Da nam

    zwykły tekst
    Natomiast

    Coś takiego-​|
    Daje

    Akapit wyrównany do prawej

    Na podobnej zasadzie działa wyśrodkowanie: jest po prostu połączeniem wyrównania do lewej i prawej:

    |​-To będzie na środku​-​|

    To będzie na środku

    Trzeba pamiętać, że działa to na cały akapit, więc przed i po wyrównywanym tekstem musi być dodatkowy enter.

    Dla dłuższych akapitów działa też justowanie - wygląda ono tak jak wyśrodkowanie, ale z = zamiast -:

    |​=Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.=|
    Daje

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

    Cytaty

    Markdown pozwala też oczywiście cytować! Zresztą, gdyby nie pozwalał, przycisk “cytuj” byłby bezużyteczny
    Choć niestety nie daje opcji dodania autora cytatu jako jego element, to nie jest to dużym problemem, bo można go umieścić nad nim jako wzmianka (@nazwa użytkownika)
    By cytować trzeba jednak dodać jeden znak na akapit. O ten:
    > Bo strzałki są fajne

    No, serio.
    To jest jednak dalej ten akapit, mimo entera.

    Ale to już nie

    By kolejne akapity były cytatem, wystarczy dodać > przed każdym z nich:

    akapit 1

    akapit 2
    dalej akapit 2

    Kod

    Coś, co raczej tu będzie mało użyteczne, ale i tak dodam: oznaczanie kodu.
    Jeśli się chce, by jakiś tekst nie był przetwarzany przez markdown, lub jego części związane z jakimś językiem programowania były kolorowane można skorzystać z tagu kodu.
    Istnieją jego dwa rodzaje:

    1. Używany wewnątrz linii.
      By dać ten tag wystarczy otoczyć tekst `takim znakiem`. Wygląda to tak.
    2. Wieloliniowy.
      Dopiero tutaj działa kolorowanie kodu. Podstawowy wygląda tak:
      ```
      jakiś kod
      dalej kod
      ```
    jakiś kod
    dalej kod
    

    Ale można też dodać język, wstawiając go w pierszej linijce wraz z `.
    ```python
    def hello_world():
        print(“hello world”)
    ```

    def hello_world():    
        print("hello world")
    

    Tabele

    No cóż, jeśli się spodziewałeś, że opiszę tutaj jak je tworzyć ręcznie, to się zawiedziesz - zajęło by to zbyt długo.
    Zamiast tego dam tu po prostu kilka linków do stron pozwalających na proste generowanie takich tabel gotowych do wstawienia:
    https://www.tablesgenerator.com/markdown_tables (generator WYSIWYG)
    https://jakebathman.github.io/Markdown-Table-Generator/ (tabele z plików csv)
    https://github.com/thisdavej/copy-excel-paste-markdown (nie jest to działająca strona, a repozytorium ze stroną do załadowania w przeglądarce pozwalającą na konwersję skopiowanych tabel z excela na markdown)

    Dodatkowo strona wspiera rozszerzenia tabel pochodzące ze specyfikacji MultiMarkdown. Pozwala to na wieloliniowe wiersze, komórki rozszerzające się na wiele kolumn lub wierszy i kilka innych małych usprawnień.
    Przykład wieloliniowych wierszy:

    |   Markdown   | Rendered HTML |
    |--------------|---------------|
    |    *Italic*  | *Italic*      | \
    |              |               |
    |    * Item 1  | * Item 1      | \
    |    * Item 2  | * Item 2      |
    |    ```python | ```python       \
    |    .1 + .2   | .1 + .2         \
    |    ```       | ```           |
    
    Markdown Rendered HTML
    *Italic*
    

    Italic

    * Item 1
    * Item 2
    • Item 1
    • Item 2
    ```python
    .1 + .2
    ```
    .1 + .2
    

    Przykład rozszerzania komórek na wiele wierszy i kolumn:

    Stage | Direct Products | ATP Yields
    ----: | --------------: | ---------:
    Glycolysis | 2 ATP ||
    ^^ | 2 NADH | 3--5 ATP |
    Pyruvaye oxidation | 2 NADH | 5 ATP |
    Citric acid cycle | 2 ATP ||
    ^^ | 6 NADH | 15 ATP |
    ^^ | 2 FADH2 | 3 ATP |
    **30--32** ATP |||
    [Net ATP yields per hexose]
    
    Net ATP yields per hexose
    Stage Direct Products ATP Yields
    Glycolysis 2 ATP
    2 NADH 3–5 ATP
    Pyruvaye oxidation 2 NADH 5 ATP
    Citric acid cycle 2 ATP
    6 NADH 15 ATP
    2 FADH2 3 ATP
    30–32 ATP

    Przykłady pochodzą z dokumentacji pluginu do markdown-it który dodaje obsługę tych opcji.


Log in to reply