04 - Markdown

Markdown¶

W tym rozdziale dowiesz się jak pisząc kod w Pythonie i tekst zachować go w dokumentacji technicznej Markdown.

Po tej części powinno być dla Ciebie jasne:

• Jak operować bezpośrednio korzystając ze składni znaczników Markdown lub trybu GUI edytora,
• Jak przejrzyście dokumentować analizę danych,
• Jak konwertować notebooki do MD w terminalu.

Markdown to prosty język znaczników. Umożliwia łatwe konwertowanie tekstu do poprawnego kodu HTML. Markdown jest używany do tworzenia notatek, dokumentacji technicznej, w komunikatorach, na forach internetowych i nie tylko.

Markdown to wygodny sposób na tworzenie sformatowanego tekstu przy użyciu prostej składni. Istnieją różne smaki markdown, ale podstawy są obsługiwane we wszystkich przypadkach i generalnie obejmują 80% przypadków użycia. HTML jest również poprawny w komórkach markdown. W rzeczywistości cały tekst i nagłówek tego notatnika to markdown/HTML. Za pomocą markdown można tworzyć nagłówki, osadzać obrazy, łączyć się z innymi stronami, tworzyć listy i nie tylko.

Markdown często używa się do tworzenia dokumantacji dla projektów programistycznych. Za jego pomocą opisuje się repozytoria kodu w popularnym serwisie GitHub, dodaj się instrukcje dla użytkowników oraz inne ważne informacje.

Z Markdown korzystają także popularne serwisy oraz pltformy blogowe takie jak Medium, Ghost albo Jekyll.

Kolejne zastosowania to aplikacje do tworzenia notatek oraz listy rzeczy do zrobienia (and. to do list). Markdown jest także używany przez popularne komunikatory oraz narzędzia do pracy zespołowej takie jak Slack czy Trello.

• 2004: John Gruber opracował Markdown.
• 2014: CommonMark został ustanowiony jako standardowa specyfikacja Markdown w celu rozwiązania niespójności i niejednoznaczności w implementacjach Markdown. Inicjatywa ta została zapoczątkowana przez Johna MacFarlane’a i wsparta przez innych entuzjastów Markdown, aby zapewnić niezawodną i spójną specyfikację.

Ten przewodnik zapewni ci kompleksowe zrozumienie kluczowych poleceń w GitHub Flavored Markdown (GFM), jest to ścisły nadzbiór CommonMark.

Filozofia¶

Markdown ma być tak łatwy do czytania i pisania, jak to tylko możliwe.

Czytelność jest jednak podkreślana ponad wszystko. Dokument sformatowany w Markdown powinien nadawać się do publikacji jako zwykły tekst, nie wyglądając na oznaczony znacznikami lub instrukcjami formatowania. Podczas gdy na składnię Markdown wpłynęło kilka istniejących filtrów tekstowych do HTML - w tym Setext, atx, Textile, reStructuredText, Grutatext i EtText - największym źródłem inspiracji dla składni Markdown jest format zwykłej wiadomości e-mail.

W tym celu składnia Markdown składa się w całości ze znaków interpunkcyjnych, które zostały starannie dobrane, aby wyglądały jak to, co oznaczają. Na przykład, gwiazdki wokół słowa wyglądają jak podkreślenie. Listy Markdown wyglądają jak, no cóż, listy. Nawet cytaty blokowe wyglądają jak cytowane fragmenty tekstu, zakładając, że kiedykolwiek korzystałeś(aś) z poczty e-mail.

Markdown jako HTML¶

Markdown nie zastępuje HTML, ani nawet nie jest do niego zbliżony. Jego składnia jest bardzo prosta i odpowiada tylko bardzo niewielkiemu podzbiorowi znaczników HTML. Ideą nie jest stworzenie składni, która ułatwi wstawianie znaczników HTML. Moim zdaniem znaczniki HTML są już łatwe do wstawienia. Ideą Markdown jest ułatwienie czytania, pisania i edytowania prozy. HTML jest formatem publikowania; Markdown jest formatem pisania. Dlatego też składnia formatowania Markdown odnosi się tylko do kwestii, które można przekazać w postaci zwykłego tekstu.

W przypadku wszelkich znaczników, które nie są objęte składnią Markdown, wystarczy użyć samego HTML. Nie ma potrzeby poprzedzania go lub ograniczania, aby wskazać, że przełączasz się z Markdown na HTML; po prostu używasz tagów.

Jedynymi ograniczeniami jest to, że elementy HTML na poziomie bloku - np. <div>, <table>, <pre>, <p>, itp. - muszą być oddzielone od otaczającej zawartości pustymi liniami, a znaczniki początkowe i końcowe bloku nie powinny być wcięte tabulatorami ani spacjami. Markdown jest wystarczająco inteligentny, aby nie dodawać dodatkowyc (niechcianych) znaczników <p> wokół znaczników na poziomie bloku HTML.

Na przykład, aby dodać tabelę HTML do artykułu Markdown:

To jest zwykły akapit.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

To jest zwykły akapit.

Znaki specjalne¶

W HTML istnieją dwa znaki, które wymagają specjalnego traktowania: < i &. Lewe nawiasy kątowe są używane do rozpoczynania znaczników; ampersandy są używane do oznaczania encji HTML. Jeśli chcesz użyć ich jako dosłownych znaków, musisz uciec od nich jako encji, np. < i &.

Ampersandy są szczególnie kłopotliwe dla autorów stron internetowych. Jeśli chcesz napisać o „AT&T”, musisz napisać „AT&T”. Ampersandów trzeba nawet unikać w adresach URL. Tak więc, jeśli chcesz połączyć się z:

http://images.google.com/images?num=30&q=larry+bird

należy zakodować adres URL jako:

http://images.google.com/images?num=30&q=larry+bird

w atrybucie href znacznika zakotwiczenia. Nie trzeba dodawać, że łatwo o tym zapomnieć i jest to prawdopodobnie najczęstsze źródło błędów walidacji HTML w dobrze oznakowanych stronach internetowych.

Markdown pozwala na używanie tych znaków w naturalny sposób, dbając o wszystkie niezbędne ucieczki. Jeśli użyjesz znaku ampersand jako części encji HTML, pozostanie on niezmieniony; w przeciwnym razie zostanie przetłumaczony na &.

Jeśli więc chcesz umieścić w swoim artykule symbol praw autorskich, możesz napisać:

© czyli ©

a Markdown pozostawi go w spokoju. Ale jeśli napiszesz:

AT&T

Markdown przetłumaczy to na:

AT&T

Podobnie, ponieważ Markdown obsługuje HTML inline, jeśli użyjesz nawiasów kątowych jako ograniczników dla znaczników HTML, Markdown potraktuje je jako takie. Ale jeśli napiszesz:

4 < 5

Markdown przetłumaczy to na:

4 < 5

Jednak wewnątrz przęseł i bloków kodu Markdown, nawiasy kątowe i ampersandy są zawsze kodowane automatycznie. Ułatwia to używanie Markdown do pisania kodu HTML. (W przeciwieństwie do surowego HTML, który jest okropnym formatem do pisania o składni HTML, ponieważ każdy pojedynczy < i & w przykładowym kodzie musi zostać uniknięty).

Elementy blokowe¶

Akapity¶

Akapit to po prostu jeden lub więcej kolejnych wierszy tekstu, oddzielonych jednym lub więcej pustymi wierszami. (Pusta linia to każda linia, która wygląda jak pusta linia - linia zawierająca tylko spacje lub tabulatory jest uważana za pustą). Normalne akapity nie powinny być wcięte spacjami lub tabulatorami.

Reguła „jednej lub więcej kolejnych linii tekstu” oznacza, że Markdown obsługuje akapity tekstowe z „twardym opakowaniem”. Różni się to znacznie od większości innych programów formatujących tekst do HTML (w tym opcji „Konwertuj podziały wiersza” Movable Type), które tłumaczą każdy znak podziału wiersza w akapicie na znacznik <br />.

Jeśli chcesz wstawić znacznik łamania <br /> za pomocą Markdown, kończysz wiersz dwiema lub więcej spacjami, a następnie wpisujesz return.

Tak, wymaga to nieco więcej wysiłku, aby utworzyć <br />, ale uproszczona reguła „każdy podział wiersza to <br /> nie działałaby w Markdown. Cytowanie blokowe w stylu e-mail i wieloakapitowe listy w Markdown działają najlepiej - i wyglądają lepiej - gdy formatujesz je z twardymi przerwami.

Nagłówki¶

Markdown obsługuje dwa style nagłówków, Setext i atx.

Nagłówki w stylu Setext są „podkreślone” za pomocą znaków równości (dla nagłówków pierwszego poziomu) i myślników (dla nagłówków drugiego poziomu). Na przykład:

To jest H1
=============

To jest H2
-------------

Dowolna liczba podkreśleń = lub - będzie działać.

Nagłówki w stylu Atx używają 1-6 znaków skrótu na początku linii, odpowiadających poziomom nagłówków 1-6. Na przykład:

# To jest H1

## To jest H2

###### To jest H6

Opcjonalnie można „zamknąć” nagłówki w stylu atx. Jest to czysto kosmetyczne - możesz tego użyć, jeśli uważasz, że wygląda to lepiej. Hasze zamykające nie muszą nawet odpowiadać liczbie haszów użytych do otwarcia nagłówka. (Liczba skrótów otwierających określa poziom nagłówka):

# To jest H1 #

## To jest H2 ##

### To jest H3 ######

Cytaty¶

Markdown używa znaków > w stylu wiadomości e-mail do cytowania blokowego. Jeśli jesteś zaznajomiony z cytowaniem fragmentów tekstu w wiadomości e-mail, to wiesz, jak utworzyć cytat blokowy w Markdown. Wygląda to najlepiej, jeśli tekst jest mocno zawinięty i umieszczony > przed każdą linią:

To jest cytat blokowy z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown pozwala być leniwym i umieszczać > tylko przed pierwszą linią mocno zawiniętego akapitu:

To jest cytat blokowy z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Cytaty blokowe mogą zawierać inne elementy Markdown, w tym nagłówki, listy i bloki kodu:

To jest nagłówek.¶

1. To jest pierwszy element listy.
2. To jest drugi element listy.

Oto przykładowy kod: return shell_exec(“echo $input |$markdown_script”);

Każdy przyzwoity edytor tekstu powinien ułatwiać cytowanie w stylu e-mail.

Listy¶

Markdown obsługuje listy uporządkowane (numerowane) i nieuporządkowane (wypunktowane).

Listy nieuporządkowane używają gwiazdek, plusów i myślników - zamiennie - jako znaczników list:

• Czerwony
• Zielony
• Niebieski

jest odpowiednikiem:

• Czerwony
• Zielony
• Niebieski

oraz:

• Czerwony
• Zielony
• Niebieski

Listy uporządkowane używają liczb, po których następują kropki:

1. Bird
2. McHale
3. Parish

Ważne jest, aby pamiętać, że rzeczywiste liczby użyte do oznaczenia listy nie mają wpływu na wynik HTML tworzony przez Markdown. HTML tworzony przez Markdown z powyższej listy to:

1. Bird

2. McHale

3. Parish

Gdyby zamiast tego napisać listę w Markdown w następujący sposób:

1. Bird
2. McHale
3. Parish

lub nawet:

3. Bird
4. McHale
5. Parish

otrzymasz dokładnie taki sam wynik HTML. Chodzi o to, że jeśli chcesz, możesz użyć liczb porządkowych w uporządkowanych listach Markdown, aby liczby w źródle odpowiadały liczbom w opublikowanym kodzie HTML. Ale jeśli chcesz być leniwy, nie musisz tego robić.

Jeśli jednak używasz leniwej numeracji list, nadal powinieneś rozpoczynać listę od liczby 1. W pewnym momencie w przyszłości Markdown może obsługiwać rozpoczynanie uporządkowanych list od dowolnej liczby.

Znaczniki list zwykle zaczynają się od lewego marginesu, ale mogą być wcięte o maksymalnie trzy spacje. Po znacznikach listy musi następować co najmniej jedna spacja lub tabulator.

* This is an unordered list
* It is useful for many things
    * Grocery lists
    * Plans to take over the world
        * Large plans may require multiple lists

• This is an unordered list
• It is useful for many things
  • Grocery lists
  • Plans to take over the world
    • Large plans may require multiple lists

1. Create an ordered list
    1. Use numbers
    1. Let the computer handle numbering
    1. Look super organized
1. Take over the world

1. Create an ordered list
   1. Use numbers
   2. Let the computer handle numbering
   3. Look super organized
2. Take over the world

Aby listy wyglądały ładnie, można zawijać elementy za pomocą wiszących wcięć:

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Ale jeśli chcesz być leniwy(a), nie musisz:

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Elementy listy mogą składać się z wielu akapitów. Każdy kolejny akapit w elemencie listy musi być wcięty o 4 spacje lub jeden tabulator:

1. To jest element listy z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

   Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

2. Suspendisse id sem consectetuer libero luctus adipiscing.

Ładnie wygląda wcięcie każdego wiersza kolejnych akapitów, ale i tutaj Markdown pozwoli ci być leniwym:

• To jest element listy z dwoma akapitami.

  To jest drugi akapit w elemencie listy. Na stronie wymagane jest tylko wcięcie pierwszego wiersza. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

• Kolejny element tej samej listy.

Aby umieścić cudzysłów blokowy w elemencie listy, > ograniczniki cudzysłowu blokowego muszą być wcięte:

• Element listy z cudzysłowem blokowym:

  To jest cytat blokowy

wewnątrz elementu listy.

Aby umieścić blok kodu wewnątrz elementu listy, blok kodu musi być dwukrotnie wcięty - 8 spacji lub dwie tabulacje:

• Element listy z blokiem kodu:

    <kod tutaj>

Warto zauważyć, że możliwe jest przypadkowe wywołanie uporządkowanej listy, pisząc coś takiego:

1986. Co za wspaniały sezon.

Innymi słowy, sekwencja cyfra-okres-spacja na początku wiersza. Aby tego uniknąć, można wstawić kropkę z odwrotnym ukośnikiem:

1986. Co za wspaniały sezon.

Umieszczanie kodu¶

Wstępnie sformatowane bloki kodu są używane do pisania o programowaniu lub kodzie źródłowym znaczników. Zamiast tworzyć normalne akapity, wiersze bloku kodu są interpretowane dosłownie. Markdown umieszcza blok kodu w znacznikach <pre> i <code>.

Aby utworzyć blok kodu w Markdown, wystarczy wciąć każdy wiersz bloku o co najmniej 4 spacje lub 1 tabulator. Na przykład, biorąc pod uwagę te dane wejściowe: to jest kod

To jest normalny akapit:

To jest blok kodu.

Markdown wygeneruje:

To jest normalny akapit:

To jest blok kodu.

Jeden poziom wcięcia - 4 spacje lub 1 tabulator - jest usuwany z każdej linii bloku kodu. Na przykład to:

Oto przykład AppleScript:

tell application “Foo” beep end tell

zamieni się w:

Oto przykład AppleScript:

tell application "Foo"
 beep
end tell

Blok kodu jest kontynuowany aż do osiągnięcia linii, która nie jest wcięta (lub końca artykułu).

Reguły poziome¶

Znacznik reguły poziomej (<hr />) można utworzyć, umieszczając trzy lub więcej myślników, gwiazdek lub podkreśleń w jednej linii. Jeśli chcesz, możesz użyć spacji między myślnikami lub gwiazdkami. Każda z poniższych linii utworzy regułę poziomą:

* * *


***


*****


- - -


---------------------------------------

Linki¶

Markdown obsługuje dwa style linków: inline i reference.

W obu stylach tekst linku jest ograniczony przez [nawiasy kwadratowe].

Aby utworzyć link wbudowany, użyj zestawu zwykłych nawiasów bezpośrednio po nawiasie kwadratowym zamykającym tekst linku. Wewnątrz nawiasów umieść adres URL, na który ma wskazywać link, wraz z opcjonalnym tytułem linku, otoczonym cudzysłowem. Na przykład:

To jest [an example](http://example.com/ „Title”) link w tekście.

Ten link nie ma atrybutu tytułu.

Spowoduje to wyświetlenie:

To jest

przykład inline link.

Ten link nie ma atrybutu title.

Jeśli odwołujesz się do lokalnego zasobu na tym samym serwerze, możesz użyć ścieżek względnych:

Szczegóły na stronie About.

Odnośniki w stylu referencyjnym używają drugiego zestawu nawiasów kwadratowych, wewnątrz których umieszcza się wybraną etykietę identyfikującą odnośnik:

To jest przykładowy link w stylu odnośnika.

Opcjonalnie można użyć spacji do oddzielenia zestawów nawiasów:

To jest [przykład] id łącze w stylu odnośnika.

Następnie w dowolnym miejscu w dokumencie można zdefiniować etykietę łącza w następujący sposób, w osobnym wierszu:

To znaczy:

Nawiasy kwadratowe zawierające identyfikator łącza (opcjonalnie wcięte od lewego marginesu przy użyciu maksymalnie trzech spacji);

• po którym następuje dwukropek;
• po którym następuje jedna lub więcej spacji (lub tabulatorów);
• po którym następuje adres URL łącza;
• po którym opcjonalnie następuje atrybut tytułu łącza, ujęty w podwójne lub pojedyncze cudzysłowy lub ujęty w nawiasy.

Poniższe trzy definicje linków są równoważne:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

Domyślny skrót nazwy łącza pozwala pominąć nazwę łącza, w którym to przypadku sam tekst łącza jest używany jako nazwa. Wystarczy użyć pustego zestawu nawiasów kwadratowych - np. aby połączyć słowo „Google” ze stroną google.com, wystarczy napisać:

Google

A następnie zdefiniować link:

Ponieważ nazwy linków mogą zawierać spacje, ten skrót działa nawet w przypadku wielu słów w tekście linku:

Odwiedź Daring Fireball, aby uzyskać więcej informacji.

A następnie zdefiniuj link:

Definicje linków można umieszczać w dowolnym miejscu w dokumencie Markdown. Zazwyczaj umieszczam je bezpośrednio po każdym akapicie, w którym są używane, ale jeśli chcesz, możesz umieścić je wszystkie na końcu dokumentu, podobnie jak przypisy.

Oto przykład linków referencyjnych w akcji:

Uzyskuję 10 razy więcej ruchu z Google [1] niż z [Yahoo] [2] lub [MSN] [3].

[1]: http://google.com/ "Google" [2]: http://search.yahoo.com/ "Yahoo Search" [3]: http://search.msn.com/ "MSN Search"

Wyróżnienia¶

Markdown traktuje gwiazdki (*) i podkreślenia (_) jako wskaźniki podkreślenia. Tekst zawinięty w jedną * lub _ zostanie zawinięty w znacznik HTML <em>, podwójne * lub _ zostaną zawinięte w znacznik HTML <strong>. Na przykład, to wejście:

*pojedyncze gwiazdki*

_pojedyncze podkreślenia_

**podwójne gwiazdki**

__podwójne podkreślenia__

wygeneruje:

pojedyncze gwiazdki

pojedyncze podkreślenia

podwójne gwiazdki

podwójne podkreślenia

Możesz użyć dowolnego stylu; jedynym ograniczeniem jest to, że ten sam znak musi być użyty do otwarcia i zamknięcia zakresu podkreślenia.

Podkreślenie może być użyte w środku słowa:

unfriggingbelievable

Ale jeśli otoczysz * lub _ spacjami, będzie to traktowane jako dosłowna gwiazdka lub podkreślenie.

Aby utworzyć dosłowną gwiazdkę lub podkreślenie w miejscu, w którym w przeciwnym razie zostałoby użyte jako separator podkreślenia, można uciec od ukośnika odwrotnego:

*ten tekst jest otoczony dosłownymi gwiazdkami*

Kod¶

Aby wskazać zakres kodu, zawiń go w cudzysłów (`). W przeciwieństwie do wstępnie sformatowanego bloku kodu, zakres kodu wskazuje kod w normalnym akapicie. Na przykład:

Użyj funkcji printf().

wygeneruje:

Użyj funkcji printf().

Aby zawrzeć dosłowny znak backtick w rozpiętości kodu, możesz użyć wielu backticków jako ograniczników otwierających i zamykających:

To jest pojedynczy backtick (`) tutaj.

co da następujący wynik:

To jest pojedynczy backtick (`) tutaj.

Ograniczniki backtick otaczające zakres kodu mogą zawierać spacje - jedną po otwierającej, jedną przed zamykającą.

Pozwala to na umieszczenie dosłownych znaków backtick na początku lub na końcu zakresu kodu:

Pojedynczy backtick w rozpiętości kodu:

Ciąg ograniczony backtickiem w rozpiętości kodu: `foo`

spowoduje:

Pojedynczy backtick w zakresie kodu: `

Ciąg ograniczony backtickiem w rozpiętości kodu: `foo`

W przypadku rozpiętości kodu, znaki ampersand i nawiasy kątowe są automatycznie kodowane jako encje HTML, co ułatwia dołączanie przykładowych znaczników HTML. Markdown zamieni to:

Please don’t use any <blink> tags.

w:

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

Możesz napisać to:

— jest zakodowanym dziesiętnie odpowiednikiem —.

aby uzyskać:

<p><code>&amp;#8212;</code> jest zakodowanym dziesiętnie odpowiednikiem <code>&amp;mdash;</code>.</p>

Obrazki¶

Trzeba przyznać, że dość trudno jest opracować „naturalną” składnię do umieszczania obrazów w zwykłym dokumencie tekstowym.

Markdown używa składni obrazów, która ma przypominać składnię linków, pozwalając na dwa style: inline i reference.

Składnia obrazków inline wygląda następująco:

![Opis obrazka](p4ds.png)

![Opis obrazka](p4ds.png "Opcjonalny tytuł")

To znaczy:

Wykrzyknik: !

• po którym następuje zestaw nawiasów kwadratowych, zawierający tekst atrybutu alt dla obrazu;
• po którym następuje zestaw nawiasów, zawierający adres URL lub ścieżkę do obrazu oraz opcjonalny atrybut title ujęty w podwójne lub pojedyncze cudzysłowy.

Składnia obrazu w stylu odniesienia wygląda następująco:

![Opcjonalny tytuł][id]

Gdzie „id” jest nazwą zdefiniowanego odniesienia do obrazu. Odniesienia do obrazów są definiowane przy użyciu składni identycznej z odniesieniami do linków:

[id]: p4ds.png "Opcjonalny tytuł"

W chwili pisania tego tekstu Markdown nie ma składni do określania wymiarów obrazu; jeśli jest to dla Ciebie ważne, możesz po prostu użyć zwykłych znaczników HTML <img>.

Tabele¶

Tworzenie tabel jest okropne w HTML. Markdown (a właściwie multi-markdown) tworzy naprawdę dobrze wyglądające tabele z prostym wprowadzaniem tekstu.

| Date | Max Temp | Min Temp |
| :---: | :---: | :---: |
| 4/12 | 75       | 65       |
| 4/13 | 80       | 68       |
| 4/14 | 68       | 50       |

Równania¶

Notatniki obsługują MathJax, więc używając podzbioru składni $\LaTeX$, można łatwo renderować złożone równania w komórkach notatnika. Nie mamy czasu, aby zagłębiać się w szczegóły składni, ale można znaleźć wiele samouczków na ten temat. Pokazanie kilku przykładów da ci jednak pewien pomysł!

Aby umieścić równania w linii z tekstem, umieść je w $, aby umieścić je w osobnych liniach, umieść je w $$.

Zacznijmy od prostego przykładu, drugiego prawa Newtona:

$$F = m a$$

Możemy również składać znacznie bardziej skomplikowane równania przy nieco większym wysiłku składniowym:

$$\left( \frac{Dv}{Dt} \right) = -2 \Omega u \text{sin}\phi - \frac{u^2}{a} \text{tan}\phi$$

$$\frac{\partial\zeta}{\partial t} = - V \cdot \nabla(\zeta + f) - \omega \frac{\partial \zeta}{\partial p}
- (\zeta + f) \nabla \cdot V + k \cdot \left(\frac{\partial V}{\partial p} \times \nabla \omega \right)$$

Przykładowe wyrazenia / funkcje¶

Specjalne znaki / Symbole¶

Łacińskie¶

Bez kropki¶

\imath $\rightarrow$ $\imath$, \jmath $\rightarrow$ $\jmath$

Daszek¶

\hat{\imath} $\rightarrow$ $\hat{\imath}$, \hat{\jmath} $\rightarrow$ $\hat{\jmath}$

Greckie litery¶

Wielkie¶

Małe¶

Inne¶

Inne symbole¶

Wyrazenia logiczne¶

Wyrazenia binarne¶

Wyrazenia sumy¶

Nazwane operatory¶

Latex - ściąga¶

Cheatsheet dla LaTexa, używający Markdown jako język znaczników dla wszystkich, których Latex trochę przeraża :-) a potrzebują wzorków w swoich dokumentach technicznych z analizy danych.

Więcej opisu znajdziecie tutaj: https://tug.ctan.org/info/short-math-guide/short-math-guide.pdf.

Dodatkowo, na repo załączam ściągawkę w wersji do wydruku A4 w PDF tutaj: latexsheet-a4.pdf

Polecane¶

Aby jeszcze bardziej Tobie pomóc w nauce tworzenia dokumentów technicznych z Markdown poniżej lista polecanych źródeł i ściąga:

• [Ściąga Markdown - Cheat Sheet](markdown-cheatsheet.pdf)
• Markdown Guide
• Bardzo przyjemne generowanie równań w Latex dla początkujących

Konwersja do MD¶

Dokumenty wszelkiego typu konwertować mozna do MD za pomocą przyjemnej w uzyciu funkcji ‘nbconvert’. Strona domowa pakietu - tutaj.

Wykorzystanie konwertera sprowadza się do napisania w terminalu:

$ jupyter nbconvert --to FORMAT notebook.ipynb

Zerknij także na poniższy tutorial:

Przydatne¶

1. Stwórz spis treści w Markdown - binarytree, github-markdown-toc
2. Stwórz pustą tabelkę w Markdown - Tablesgenerator
3. Konwersja Excel do tabeli Markdown - Tableconvert
4. Podgląd Markdown dla Sublime Text 3 - Packagecontrol
5. Podgląd Markdown dla Visual Studio Code - Markdown Preview Enhanced
6. Kolekcja przydatnych narzędzi dla Markdown - Awesome Markdown
7. Markdownlint - markdownlint, markdownlint-cli2, markdownlint-cli2-action, vscode-markdownlint
8. Lekkie narzędzia dla Pythona do konwertowania różnych plików do Markdown - Markitdown
9. Serwer SSE MCP do wywoływania MarkItDown - MarkItDown-MCP

Zapoznaj się z oficjalną dokumentacją na GitHub, aby dowiedzieć się więcej o pisaniu i formatowaniu składni. Ponadto możesz zapoznać się z najnowszymi aktualizacjami i funkcjami Markdown, odwiedzając GitHub changelog posts.