Poznaj Markdown: narzędzie do pisania dla programistów

Jeśli jesteś inżynierem oprogramowania, prawdopodobnie spędziłeś dużo czasu na udoskonalaniu środowiska w celu zwiększenia produktywności. Masz swoje ulubione IDE. Masz swój ulubiony debugger. Masz swoje ulubione narzędzie do monitorowania wydajności. Ale co z twoim narzędziem do pisania dokumentacji, podręczników i raportów? W końcu pisanie zajmuje ci nietrywialną ilość czasu, prawda? Rzeczywiście, nadszedł czas, aby poważnie potraktować swoje narzędzie do pisania.

I pamiętajmy, że jesteś techniczny , więc edytory WYSIWYG mogą, ale nie muszą być dla Ciebie najlepszą opcją. Niekoniecznie chcesz (a nawet chcesz!) nawigować po menu, paskach narzędzi i wstążkach, aby sformatować tekst.

A co, jeśli zamiast tego możesz łatwo dodać wszystkie style formatowania bezpośrednio do tekstu jako prostą składnię wbudowaną, aby uzyskać w pełni sformatowany tekst?

Cóż, w rzeczywistości możesz. To jest Markdown io tym jest ten samouczek.

Kiedy więcej znaczy mniej…

Oprogramowanie do przetwarzania tekstu zostało napisane, aby zadowolić niezwykle szeroką gamę użytkowników i przypadków użycia, i jako takie musi zapewniać wszelkiego rodzaju funkcje. Ale oczywiście tylko niewielki podzbiór tej funkcji może być istotny dla każdego indywidualnego użytkownika. A dla większości użytkowników, którzy po prostu chcą napisać dokument (i nie muszą projektować broszury marketingowej ani plakatu), istotny jest bardzo mały podzbiór z wielu dostępnych opcji.

W rzeczywistości Microsoft wyraźnie zdał sobie z tego sprawę kilka lat temu, kiedy przeprojektował interfejs użytkownika programu Microsoft Word w odrębne grupy funkcjonalne, które nazwali „wstążkami”. Co ciekawe, większość użytkowników powie, że nowy interfejs jest dla nich bardziej zagmatwany i trudniejszy w nawigacji niż jego poprzednik.

Rzeczywiście, czasem więcej może oznaczać mniej, jeśli chodzi o łatwość użytkowania i produktywność.

… i kiedy mniej znaczy więcej

Spójrz prawdzie w oczy, jesteś inżynierem oprogramowania, a nie grafikiem. Po prostu chcesz napisać tę instrukcję, dokument techniczny lub raport i skończyć z tym. Będziesz bardzo zadowolony i zadowolony z podstawowych funkcji formatowania, takich jak nagłówki, listy punktowane lub numerowane oraz bloki kodu. I tak, trochę formatowania czcionek (pogrubienie, kursywa itp.) również byłoby pomocne. O to chodzi. (Człowieku, gdybyś mógł to zrobić w vi, to byłoby naprawdę niesamowite!)

Wprowadź przecenę.

Co to jest przecena?

John Gruber (przy znacznym udziale guru technicznego i aktywisty internetowego Aarona Swartza) stworzył język Markdown w 2004 roku w celu umożliwienia ludziom „pisania w łatwym do odczytania, łatwym do pisania formacie zwykłego tekstu i opcjonalnie przekonwertuj go na poprawny strukturalnie XHTML (lub HTML)”.

Markdown został zaprojektowany tak, aby był czytelny w stanie, w jakim jest, bez wyglądania, jakby został oznaczony znacznikami lub instrukcjami formatowania (w przeciwieństwie do tekstu sformatowanego w języku znaczników, takim jak RTF lub HTML, który może być zarówno trudny do napisania, jak i trudny do odczytania w jego surowym formacie ).

Markdown umożliwia pisanie przy użyciu łatwego do odczytania, łatwego do zapisania formatu zwykłego tekstu, który można następnie przekonwertować na poprawny strukturalnie kod HTML. Tak więc, aby być całkowicie precyzyjnym, Markdown to tak naprawdę dwie rzeczy:

1. Składnia formatowania zwykłego tekstu
2. Narzędzie programowe (którego pierwsza wersja została napisana w Perlu), które konwertuje formatowanie zwykłego tekstu na HTML.

Markdown zawiera kilka prostych, dość intuicyjnych i łatwych w użyciu konwencji składni. Specjalnie dla Ciebie jako inżyniera oprogramowania – który nie zraża się koniecznością uczenia się i używania tych podstawowych konwencji składni – Markdown może rzeczywiście być ścieżką najmniejszego oporu między tym, co chcesz napisać, a napisaniem tego.

Naucz się przecen: Pierwsze kroki

Przecena jest łatwa do nauczenia. Super łatwe. Podstaw można nauczyć się w pięć minut i szybko stanie się to drugą naturą. I – podobnie jak w przypadku relacji między preprocesorami CSS i CSS – możesz używać tak mało, jak chcesz.

Jeśli jesteś przyzwyczajony do jakichkolwiek konwencji pisania zwykłego tekstu, być może znasz już niektóre konwencje przecenowe, takie jak liczby lub myślniki na początku zdania w celu utworzenia listy, gwiazdki wokół słowa z podkreśleniem itp. na. Na przykład, jeśli chcesz wyświetlić coś kursywą, po prostu zawiń to w gwiazdki, takie jak *this* (w przeciwieństwie do bardziej niezgrabnej składni HTML, takiej jak <span>this</span> ).

Podobnie możesz określić nagłówek H1, dodając po prostu przedrostek „#” do wiersza (np. # Section Heading , a nie <h1>Section Heading</h1> ).

Innym świetnym zastosowaniem do nauki języka Markdown, szczególnie dla nas, inżynierów oprogramowania, jest użycie go do dokumentacji w repozytoriach kodu źródłowego. Większość repozytoriów zawiera plik README.md ( .md to standardowe rozszerzenie pliku Markdown). Na przykład Github ma swój własny „Markdown w stylu Github”, który dodaje dodatkowe funkcje przeznaczone specjalnie do dokumentacji programistycznej. To z pewnością może zaoszczędzić czas na pisanie tej dokumentacji w HTML.

Jako prosty przykład załóżmy, że chcesz dołączyć do dokumentacji następujący fragment:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Inicjowanie wtyczek</h2>

Zainicjuj pluginName w swoim kontenerze za pomocą jQuery w następujący sposób:

$(function() { $('#container').pluginName(); }); Używając identyfikatora naszego kontenera, możemy zainicjować pluginName za pomocą metody jQuery .pluginName() .

Oto porównanie, jak można to zrobić w HTML i Markdown:

Aby uzyskać dalszą pomoc w rozpoczęciu pracy, dostępnych jest wiele samouczków dotyczących Markdown online, które pomogą Ci na bieżąco, w tym przegląd Markdown autorstwa Johna Grubera (twórcy Markdown) oraz samouczek online Markdown.

Parsery i narzędzia przecenowe

Po napisaniu artykułu w Markdown będziesz potrzebować aplikacji do przeanalizowania składni na HTML. Jest kilka świetnych, które są bezpłatne , w tym:

• StackEdit — oparty na przeglądarce edytor Markdown, który ma kilka opcji synchronizacji z popularnymi usługami, takimi jak Dysk Google i Dropbox
• Online Kramdown Editor - kolejny edytor Markdown oparty na przeglądarce z niezwykle prostym interfejsem
• Mou - najlepszy program do tworzenia Markdownów na Maca, z którym spotkałem się jako ciekawsza opcja dla programistów; mnóstwo funkcji i za darmo (w wersji beta) [tak pisałem ten artykuł]
• MarkdownPad - świetny edytor Markdown dla Windows
• Teksty - ładny wieloplatformowy edytor (Mac i Windows); eksport do wielu formatów, takich jak PDF, .doc i ePub

Niektóre główne platformy już przyjęły (lub przynajmniej dopuściły) używanie Markdown w swoich edytorach dla tych, którzy chcą z niego korzystać. W przypadku innych, takich jak WordPress, Evernote i Google Docs, natywna obsługa (w momencie pisania tego artykułu) nie jest jeszcze zapieczętowana, ale niestandardowe rozwiązania zostały wprowadzone przez strony trzecie. Obejmują one:

• Popularna nowa platforma blogowa Ghost, dążąc do usprawnienia pisania online, używa Markdown jako edytora treści.
• W przypadku WordPress wtyczka Jetpack oficjalnie obsługuje teraz Markdown, którą możesz włączyć w Ustawienia> Dyskusja , jeśli używasz wtyczki. Możesz też użyć wtyczki, takiej jak WP-Markdown, która przekonwertuje zawartość postów z przecenami na HTML i z powrotem do Markdown, gdy zajdzie potrzeba jej edycji.
• W przypadku Evernote niektóre aplikacje Markdown, takie jak edytor online Markable lub edytor Mac Byword, umożliwiają eksportowanie i publikowanie bezpośrednio do notatek. Lub, jeśli wolisz bezpośrednio korzystać z aplikacji internetowej Evernote, możesz użyć rozszerzenia przeglądarki o nazwie Markdown Here, które konwertuje wybraną notatkę zapisaną w Markdown na sformatowany tekst za pomocą kliknięcia przycisku paska narzędzi.
• Dokumenty Google nie obsługują jeszcze języka Markdown natywnie, ale kilka edytorów (takich jak StackEdit) eksportuje/synchronizuje bezpośrednio z Dyskiem.

Wady

Oczywiście z dużą prostotą wiążą się ograniczenia. Jak już wyjaśniłem, Markdown nie został napisany do złożonych zadań przetwarzania tekstu wymagających zaawansowanych funkcji formatowania. Jeśli tego potrzebujesz, Markdown nie jest właściwym narzędziem.

Jednak programistom, którzy potrzebują napisać podręcznik użytkownika, dokumentację techniczną lub raport techniczny, Markdown zapewnia niemal idealną równowagę między prostotą a funkcjami, których potrzebujesz.

Być może największą wadą – szczególnie dla nas, inżynierów, którzy są maniakami kontroli zmian – jest brak możliwości wspólnej pracy w Markdown i śledzenia zmian (jednak jednym godnym uwagi wyjątkiem jest wtyczka StackEdit dla Dokumentów Google). I oczywiście przy minimalnym nakładzie pracy można po prostu współpracować nad dokumentem Markdown za pośrednictwem repozytorium git, a tym samym uzyskać całe śledzenie zmian i współpracę, których zwykle potrzebujemy.

Wniosek

Czy więc nauka Markdown jest dla wszystkich? Oczywiście nie. Żadne narzędzie nigdy nie jest.

Ale jeśli jesteś inżynierem oprogramowania, może to być dokładnie narzędzie do pisania, którego szukasz. Więc jeśli jeszcze tego nie spróbowałeś, naprawdę powinieneś wziąć to na przejażdżkę.