Markdown - the markup language

5 may 2022
Jakub Rojek Jakub Rojek
Photo by Tirachard Kumtanom from Pexels (https://www.pexels.com/pl-pl/zdjecie/bialy-pusty-notatnik-733857/)
Categories: IT fundamentals

Gdy myślimy o pisaniu tekstów na komputerze, pierwsza lampka, która nam się zapala, dotyczy pakietu Office oraz programu Microsoft Word lub ich darmowych odpowiedników (np. OpenOffice, LibreOffice). Niektórzy zapewnie wolą przygotowywać opisy w programach podobnych do Notepada (zwłaszcza Notepad++, który jest jednym z najlepszych edytorów tekstowych), a dopiero później przenosić do bardziej zaawansowanych aplikacji. Jeszcze inni stwierdzą, że narzędzia instalowane na komputerze to przeżytek i od razu swoje oczy skierują na Google Docs.

Czy można podejść do tego inaczej? Oczywiście - wystarczy użyć jednego z języków znaczników i przygotować sobie skrypt do budowania dokumentów. "Ale że co?!", pewnie niektórzy zapytają.

Czym są języki znaczników?

"Standardowe" (tzn. takie, które zna większość użytkowników) edytory tekstowe to tak zwane edytorzy WYSIWYG, co jest akronimem od What You See Is What You Get - już tworząc dokument widzimy jego docelową formę i mamy wiele graficznych narzędzi, które pomogą nam przygotować taki tekst, jaki chcemy. Alternatywą jest WYWIWYG, w którym "S" (See) zmienia się na "W" (Write) - w takich programach użytkownik widzi nie docelową formę, ale kod dokumentu, który dopiero później zostanie przetworzony przez odpowiednie narzędzie do estetycznej formy (najczęściej w formie pliku PDF). Istnieją też aplikacje (także online'owe), które wyświetlają jednocześnie kod i obok podgląd generowanego dokumentu w czasie rzeczywistym - jedno takie narzędzie pokażemy sobie w tym artykule.

Język znaczników to ustalona forma kodowania dokumentu, która umożliwia odpowiedniemu narzędziu dokonania konwersji na formę estetyczną dla użytkownika. Znacznikiem jest określony znak (czasami biały) lub grupa znaków, która potrafi nam jednoznacznie określić, że np. dany fragment jest osobnym akapitem lub będzie zapisywany kursywą. Tego typu języki stosuje się przede wszystkim dla lepszej kontroli nad tekstem, ale to nie jest ich jedyna zaleta. Dla osób obeznanych z daną techniką są szybsze w tworzeniu i bardziej ustandaryzowane - z pewnością spotkaliście się z sytuacją, w której dany dokument wyglądał inaczej w starszym i nowszym Wordzie. Co prawda, w przypadku języków znaczników też może zdarzyć się taki wypadek, jednak jest to dużo rzadsze, gdyż standard jest jeden i twórcy narzędzi starają się go trzymać. Kodowanie dokumentu jest też lepsze w zespołowej pracy nad dokumentem, gdyż z racji operowania na plikach tekstowych, z prawidłowym przekazywaniem zmian bez problemu poradzi sobie system kontroli wersji, jak np. Git.

Najprostszym przykładem jezyka znaczników jest HTML, w którym znaczniki są bardziej znane pod nazwą tagów. Jest to chyba najbardziej upowszechniona forma zapisu dokumentów, oczywiście związana głównie ze stronami WWW. Natomiast dzisiaj skupimy się bardziej na językach stricte związanych z dokumentami nieinternetowymi - takimi formami są np. notacja wiki, LaTeX, reStructuredText czy bohater dzisiejszego tekstu, Markdown.

Najczęściej języki znaczników kojarzone są z edytorami WYWIWYG, gdzie tekst powstaje w edytorze typowo tekstowym (np. w Notepadzie++ lub Vimie), a dopiero potem wykorzystuje się odpowiednie polecenia w konsoli. Trzeba jednak nadmienić, że przez lata powstały już wygodne narzędzia WYSIWYG, zatem taka forma zapisu jest bardziej przyjazna użytkownikom, którzy z jakąkolwiek formą programowania są na bakier.

Dlaczego warto znać Markdowna?

Markdown związany jest z plikami o rozszerzeniu .md i programiści powinni doskonale go kojarzyć z plikiem README.md, który domyślnie określa instrukcję dla danego programu i jest wyświetlany w repozytorium przez GitHuba, np. na naszym repozytorium. Jednak bardzo szybko zauważono, że ten język jest na tyle prosty (wręcz minimalistyczny), że nada się do tworzenia dokumentów o bardziej ogólnym, choć nadal technicznym przeznaczeniu. Nietrudno wyobrazić sobie zastosowanie Markdowna do pisania instrukcji, specyfikacji czy nawet książki, a więc wszystkich dokumentów, w których liczy się treść, a formatowanie jest minimalne i dotyczy bardziej struktury tekstu (nagłówki itd.). Pliki .md są w tym lepsze niż przykładowo wymagający dużej wiedzy LaTeX, wykorzystywany w opracowaniach naukowych ze względu na wsparcie dla wzorów matematycznych.

Osoby zaznajomione z Markdownem zapewne nadal będą korzystać z edytorów tekstowych i skryptów, jednak ten język znaczników jest o tyle warty nauczenia się, gdyż jest jest wykorzystywany w coraz większej liczbie narzędzi. Oprócz wspomnianego GitHuba, można w nim pisać także w Dropbox Paper (właśnie jako WYSIWYG), a od niedawna także w Google Docs. W tej drugiej aplikacji, po włączeniu interpretacji instrukcji Markdowna (Narzędzia -> Ustawienia -> Automatycznie wykrywaj format Markdown), pisany kod będzie automatycznie tłumaczony na formę graficzną.

Przykład dokumentu w Markdownie

Zerknijmy na następujący kod:

# Kontekst i cel biznesowy

## Opis problemu

Problem opisywany przez klienta jest następujący:

* powód 1
* powód 2
* powód 3

## Kontekst

Firma klienta składa się z działu **biznesowego** i _technicznego_. Najważniejsi udziałowcy to:

1. Osoba 1
2. Osoba 2

## Opis udziałowców

### Osoba 1

Szczegóły można przeczytać [pod tym linkiem](https://wildasoftware.pl)
![A to logo firmy](https://wildasoftware.pl/img/wilda_logo_dark_blue.png)

### Osoba 2

Brak informacji

W powyższym dokumencie widzimy, że mamy tekst podzielony na nagłówki - są to te hashe (#), które w określonej liczbie pokazują stopień zagłębienia danego nagłówka. Linie są oddzielone światłem, jednak tak naprawdę tutaj nie było to potrzebne i to wyłącznie zabieg dydaktyczny - w tak krótkim tekście z taką liczbą nagłówków akapity utworzą się automatycznie, natomiast standardowo, każda wolna linia daje jeszcze więcej przestrzeni pomiędzy kawałkami tekstu.

Kod pokazuje również, że tekst można wytłuścić oraz napisać kursywą. Możliwe są także wypunktowania i wyliczenia. Dodatkowo, co nie zostało pokazane, możemy oznaczać fragmenty tekstu jako kod, cytat, a także podawać linki czy ścieżki do obrazów. Nie wszystko działa w Google Docs, jednak bez problemu można to wykorzystywać podczas tworzenia dokumentu na swoim komputerze. Te znaczniki zostały dobrze zaprezentowane na stronie w Wikipedii.

Wspomniałem o narzędziach pokazujących jednocześnie kod źródłowy dokumentu oraz formę graficzną. Przykładem dla Markdowna jest StackEdit, w którym powyższy dokument po sformatowaniu wygląda właśnie tak:

Widok dokumentu wygenerowanego na podstawie powyższego kodu

Podsumowanie

Jak widać, Markdown jest naprawdę minimalistyczny i nie wymaga długiego wdrażania się, a efekty są zadowolające w przypadku dokumentów, w których najważniejsza jest struktura. Co więcej, języki znaczników tego typu zapewne będą zyskiwać na znaczeniu i coraz mniejszym powodzeniem będzie cieszyła się wymówka "bo ja nie jestem programistą". Warto poznawać nowe techniki tworzenia dokumentów - szczególnie, jeśli piszemy ich dużo i w większej liczbie osób.

Pozdrawiam i dziękuję - Jakub Rojek.

We can do quite a bit and what is more, our skills and resources are at your disposal. Take a peek at what we can offer you.

About author

Jakub Rojek

Lead programmer and co-owner of Wilda Software, with many years of experience in software creation and development, but also in writing texts for various blogs. A trained analyst and IT systems architect. At the same time he is a graduate of Poznan University of Technology and teaches at this university. In his free time, he enjoys playing video games (mainly card games), reading books, watching american football and e-sport, discovering heavier music, and pointing out other people's language mistakes.

Jakub Rojek