Spis teści:
Wstęp
Akapity
Podstawowe formatowanie
Linki i obrazy
Nagłówki
Listy
Kolory
Spoilery
Wyrównywanie tekstu
Cytaty
Kod
Tabele
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:
Na przykład:
 da nam
Przykład
Tekst alternatywny nie jest oczywiście potrzebny (można napisać , 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
pierwszy element
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
Pierwszy stopień
Drugi stopień
Trzeci stopień
Znowu drugi stopień
I znowu pierwszy
Można też spokojnie mieszać rodzaje:
Element z punktorem
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:
%(#FF0000)[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:
Spoiler
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:
Używany wewnątrz linii.
By dać ten tag wystarczy otoczyć tekst `takim znakiem`. Wygląda to tak.
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]
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]
Przykłady pochodzą z dokumentacji pluginu do markdown-it który dodaje obsługę tych opcji.
