Markdown

Jeszenszky PéterDebreceni Egyetem, Informatikai Kar

jeszenszky.peter@inf.unideb.hu

Utolsó módosítás: 2020. szeptember 28.

mailto:jeszenszky.peter@inf.unideb.hu

2

Jelölőnyelvek● A jelölőnyelvek szöveg annotálására szolgáló

számítógépes nyelvek.– Lehetővé teszik szövegrészekhez metaadatok megadását a

szövegtől jól elkülöníthető módon.● Példák:

– TeX, LaTeX https://www.latex-project.org/– Markdown https://daringfireball.net/projects/markdown/– troff (man oldalak) https://www.gnu.org/software/groff/– XML https://www.w3.org/XML/– Wikitext https://en.wikipedia.org/wiki/Help:Wikitext

https://www.latex-project.org/https://daringfireball.net/projects/markdown/https://www.gnu.org/software/groff/https://www.w3.org/XML/https://en.wikipedia.org/wiki/Help:Wikitext

3

Mi a Markdown?

● A Markdown egy pehelysúlyú jelölőnyelv sima szöveges formázási szintaxissal.– Lásd: https://en.wikipedia.org/wiki/Markdown

https://en.wikipedia.org/wiki/Markdown

4

Szimbólum

● Dustin Curtis. The Markdown Mark. https://dcurt.is/the-markdown-mark https://github.com/dcurtis/markdown-mark

https://dcurt.is/the-markdown-markhttps://github.com/dcurtis/markdown-mark

5

Jellemzők

● Könnyen olvasható és könnyen írható sima szöveges formátum.

● Különféle kimeneti formátumokba alakítható (például HTML-be).

● Kifejezetten a speciális ismeretekkel nem rendelkező felhasználókat célozza meg.

● Szintaxisát főleg a sima szöveges email formázás ihlette.

6

Használat (1)

● A Markdown-t széles körben használják a weben szövegbevitelre.

● A fő alkalmazási területek közé tartoznak:– Kollaborációs eszközök és platformok– Blogolási platformok és tartalomkezelő rendszerek– Online közösségi platformok– Műszaki és tudományos publikálás

7

Használat (2)

● Kollaborációs eszközök és platformok:– GitHub https://github.com/

● Lásd: Writing on GitHub https://help.github.com/en/categories/writing-on-github

– Trello https://trello.com/● Lásd: How To Format Your Text in Trello

https://help.trello.com/article/821-using-markdown-in-trello

https://github.com/https://help.github.com/en/categories/writing-on-githubhttps://trello.com/https://help.trello.com/article/821-using-markdown-in-trellohttps://help.trello.com/article/821-using-markdown-in-trello

8

Használat (3)

● Blogolási platformok és tartalomkezelő rendszerek:– Moodle https://moodle.org/

● Lásd: https://docs.moodle.org/en/Markdown– WordPress https://wordpress.com/

● Lásd: Using Markdown on WordPress.com https://en.support.wordpress.com/can-i-use-markdown-on-wordpress-com/

https://moodle.org/https://docs.moodle.org/en/Markdownhttps://wordpress.com/https://en.support.wordpress.com/can-i-use-markdown-on-wordpress-com/https://en.support.wordpress.com/can-i-use-markdown-on-wordpress-com/

9

Használat (4)

● Online közösségi platformok:– reddit https://www.reddit.com/

● Lásd: https://www.reddit.com/wiki/markdown– Stack Overflow https://stackoverflow.com/

● Lásd: How do I format my posts using Markdown or HTML? https://stackoverflow.com/help/formatting

https://www.reddit.com/https://www.reddit.com/wiki/markdownhttps://stackoverflow.com/https://stackoverflow.com/help/formatting

10

Használat (5)● Műszaki és tudományos publikálás:

– bookdown https://bookdown.org/– Daniel Stenberg. Everything curl.

https://curl.haxx.se/book.html https://github.com/bagder/everything-curl

– GitBook https://www.gitbook.com/● Lásd: https://docs.gitbook.com/content-editing/markdown

– Microsoft Docs https://docs.microsoft.com/● Lásd: A Docs Markdown-referenciája

https://docs.microsoft.com/hu-hu/contribute/markdown-reference

https://bookdown.org/https://curl.haxx.se/book.htmlhttps://github.com/bagder/everything-curlhttps://www.gitbook.com/https://docs.gitbook.com/content-editing/markdownhttps://docs.microsoft.com/https://docs.microsoft.com/hu-hu/contribute/markdown-referencehttps://docs.microsoft.com/hu-hu/contribute/markdown-reference

11

Történet (1)

● A Markdown-t eredetileg John Gruber fejlesztett ki 2004-ben Aaron Swartz közreműködésével.– Az alábbiak képében alkották meg:

● egy sima szöveges formátum, mely strukturált dokumentumok írására szolgál, és

● egy Perl szkript, mely a Markdown-t HTML-be alakítja (Markdown.pl).

● Webhely: https://daringfireball.net/projects/markdown/

https://daringfireball.net/projects/markdown/

12

Történet (2)

● A Markdown létrehozása mögötti indítékok:– John Gruber. Dive Into Markdown. 19 March 2004.

https://daringfireball.net/2004/03/dive_into_markdown

● Az eredeti Markdown szintaxis: https://daringfireball.net/projects/markdown/syntax– A szintaxis nem egyértelműen meghatározott.

https://daringfireball.net/2004/03/dive_into_markdownhttps://daringfireball.net/2004/03/dive_into_markdownhttps://daringfireball.net/projects/markdown/syntaxhttps://daringfireball.net/projects/markdown/syntax

13

Állomány jellemzők

● Állomány kiterjesztés: .md● Média típus: text/markdown

– Opcionális paraméter: variant● Lásd: Sean Leonard. The text/markdown

Media Type. RFC 7763. March 2016. https://tools.ietf.org/html/rfc7763

https://tools.ietf.org/html/rfc7763

14

Szintaktikus félreérthetőség (1)

● A szintaxis félreérthető elemeinek egy átfogó listáját lásd:– CommonMark Spec – Why is a spec needed?

https://spec.commonmark.org/0.29/#why-is-a-spec-needed-

● A félreérthetőség feloldásának egy lehetséges módja a Gruber által készített implementáció (Markdown.pl) forráskódjának tanulmányozása.– Az impementáció sajnos eléggé sok hibát tartalmaz.

https://spec.commonmark.org/0.29/#why-is-a-spec-needed-https://spec.commonmark.org/0.29/#why-is-a-spec-needed-

15

Szintaktikus félreérthetőség (2)

● Babelmark 2https://johnmacfarlane.net/babelmark2/– Eszköz az eredeti Markdown szintaxis különféle

implementációi által előállított kimenetek összehasonlításához.

https://johnmacfarlane.net/babelmark2/

16

Szabványosítás

● CommonMark https://commonmark.org/– A Markdown egy egyértelmű szintaxis

specifikációja.– Specifikáció: CommonMark Spec

https://spec.commonmark.org/● Egy tesztkészlet is biztosít az implementációk a

specifikációnak való megfelelésének ellenőrzéséhez.

https://commonmark.org/https://spec.commonmark.org/

17

Változatok● A Markdown-nak számos változata és kiterjesztése

létezik, mint például:– GitHub Flavored Markdown (GFM)

● Lásd: GitHub Flavored Markdown Spec https://github.github.com/gfm/– Pandoc's Markdown

● Lásd: Pandoc User’s Guide – Pandoc's Markdown https://pandoc.org/MANUAL.html#pandocs-markdown

– …● Lásd: Markdown Variants

https://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml

https://github.github.com/gfm/https://pandoc.org/MANUAL.html#pandocs-markdownhttps://www.iana.org/assignments/markdown-variants/markdown-variants.xhtmlhttps://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml

18

Oktatóanyagok

● Markdown Guide https://www.markdownguide.org/

● Markdown Tutorial https://commonmark.org/help/tutorial/

https://www.markdownguide.org/https://commonmark.org/help/tutorial/

19

Szerkesztők (1)

● Szabad és nyílt forrású szoftverek:– Visual Studio Code (platform: Linux, macOS, Windows;

licenc: MIT License) https://code.visualstudio.com/ https://github.com/Microsoft/vscode

● Lásd: https://code.visualstudio.com/docs/languages/markdown

● Javasolt kiterjesztések:– Markdown All in One

https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

– Markdown+Math https://marketplace.visualstudio.com/items?itemName=goessner.mdmath

https://code.visualstudio.com/https://github.com/Microsoft/vscodehttps://code.visualstudio.com/docs/languages/markdownhttps://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-onehttps://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-onehttps://marketplace.visualstudio.com/items?itemName=goessner.mdmathhttps://marketplace.visualstudio.com/items?itemName=goessner.mdmath

20

Szerkesztők (2)● Szabad és nyílt forrású szoftverek (folytatás):

– ghostwriter (platform: Linux, Windows; programozási nyelv: C++; licenc: GPLv3) http://wereturtle.github.io/ghostwriter/ https://github.com/wereturtle/ghostwriter

– Mark Text (platform: Linux, macOS, Windows; programozási nyelv: JavaScript; licenc: MIT License) https://marktext.app/ https://github.com/marktext/marktext

– Remarkable (platform: Linux; programozási nyelv: Python; licenc: MIT License) http://remarkableapp.github.io/ https://github.com/jamiemcg/remarkable

– StackEdit (programozási nyelv: JavaScript; licenc: Apache License 2.0) https://stackedit.io/ https://github.com/benweet/stackedit

http://wereturtle.github.io/ghostwriter/https://github.com/wereturtle/ghostwriterhttps://marktext.app/https://github.com/marktext/marktexthttp://remarkableapp.github.io/https://github.com/jamiemcg/remarkablehttps://stackedit.io/https://github.com/benweet/stackedit

21

Szerkesztők (3)

● Nem szabad szoftverek:– XML Editor https://www.oxygenxml.com/

● Lásd: https://www.oxygenxml.com/xml_editor/markdown_editor.html

– IntelliJ IDEA https://www.jetbrains.com/idea/● Az Ultimate és a közösségi kiadásban is támogatott.● Lásd: https://www.jetbrains.com/help/idea/markdown.html

https://www.oxygenxml.com/https://www.oxygenxml.com/xml_editor/markdown_editor.htmlhttps://www.oxygenxml.com/xml_editor/markdown_editor.htmlhttps://www.jetbrains.com/idea/https://www.jetbrains.com/help/idea/markdown.html

22

Konverziós eszközök

● Szabad és nyílt forrású szoftverek:– Pandoc (platform: Linux, macOS, Windows; license:

GPLv2) https://pandoc.org/ https://github.com/jgm/pandoc

● Haskell-ben írt parancssori eszköz, mely állományok egy jelölőnyelv formátumból egy másikba történő alakítására szolgál.

● A Markdown bemeneti és kimeneti formátumként is támogatott.

https://pandoc.org/https://github.com/jgm/pandoc

23

Pandoc (1)

● Telepítés: https://pandoc.org/installing.html● Használat: https://pandoc.org/MANUAL.html

pandoc --standalone --to html input.md \--output output.html --css style.css

or

pandoc -s -t html input.md -o output.html \-c style.css

https://pandoc.org/installing.htmlhttps://pandoc.org/MANUAL.html

24

Pandoc (2)

● A kimenet stilizálása CSS-sel:– A -c/--css parancssori opció egy egyéni CSS

stíluslapot társít a kimeneti dokumentumhoz.● Ez az opció többször is megadható.

25

Pandoc (3)

● Példák egyéni CSS stíluslapra:– Pan Am: Simple CSS for Pandoc (licenc: WTFPL)

https://benjam.info/pan-am/ https://github.com/bgw/pan-am

● CSS stíluslap: http://benjam.info/panam/styling.css– Tufte Pandoc CSS (licenc: MIT License)

https://jez.io/tufte-pandoc-css/ https://github.com/jez/tufte-pandoc-css

https://benjam.info/pan-am/https://github.com/bgw/pan-amhttp://benjam.info/panam/styling.csshttps://jez.io/tufte-pandoc-css/https://github.com/jez/tufte-pandoc-css

26

Pandoc (4)

● IDE integráció:– Visual Studio Code:

● vscode-pandoc https://github.com/dfinke/vscode-pandoc https://marketplace.visualstudio.com/items?itemName=DougFinke.vscode-pandoc

https://github.com/dfinke/vscode-pandochttps://marketplace.visualstudio.com/items?itemName=DougFinke.vscode-pandochttps://marketplace.visualstudio.com/items?itemName=DougFinke.vscode-pandoc

27

R Markdown (1)

● A Markdown egy kiterjesztése, mely lehetővé teszi végrehajtható kódrészek beágyazását.– Például a következő programozási nyelvek

támogatottak: Apache Groovy, Bash, Haskell, Python, R, Scala, SQL, …

● Állomány kiterjesztés: .Rmd● Webhely: https://rmarkdown.rstudio.com/

https://rmarkdown.rstudio.com/

28

R Markdown (2)

● Megvalósítás egy R csomagként (rmarkdown). https://cran.r-project.org/web/packages/rmarkdown/

https://cran.r-project.org/web/packages/rmarkdown/https://cran.r-project.org/web/packages/rmarkdown/

29

R Markdown (3)● Támogatott kimeneti formátumok: HTML, PDF,

PowerPoint, MS Word, …● PDF kimenet előállításához TeX rendszer szükséges.

– A rendelkezésre álló lehetőségek egy listáját lásd: https://www.latex-project.org/get/#tex-distributions

– A TeX telepítésének legegyszerűbb módja R felhasználók számára:

● TinyTeX https://yihui.org/tinytex/– Egy pehelysúlyú, platformfüggetlen és hordozható TeX disztribúció, mely a TeX

Live-on alapul.– A tinytex R csomag szolgál a TinyTeX telepítésére. A telepítéshez nem

szükséges adminisztrátori jogosultság.

https://www.latex-project.org/get/#tex-distributionshttps://yihui.org/tinytex/

30

R Markdown (4)

● Dokumentáció:– Yihui Xie, J. J. Allaire, Garrett Grolemund. R

Markdown: The Definitive Guide. 2019. https://bookdown.org/yihui/rmarkdown/ https://github.com/rstudio/rmarkdown-book

● Eszköztámogatás:– RStudio https://www.rstudio.com/

https://bookdown.org/yihui/rmarkdown/https://github.com/rstudio/rmarkdown-bookhttps://www.rstudio.com/

31

R Markdown (5)

● Az rmarkdown csomag a knitr csomagtól függ.– A kintr egy R csomag dinamikus jelentések

létrehozásához.– A Markdown kódba beágyazott programkód

kiértékelésére és az eredmény beillesztésére szolgál.

– Webhely: https://yihui.org/knitr/ https://github.com/yihui/knitr

https://yihui.org/knitr/https://github.com/yihui/knitr

32

R Markdown (6)

● Konverzió:

file.Rmd knitr file.md pandoc file.html

file.doc

file.pdf

33

R Markdown (7)---title: "R Markdown Example"author: Péter Jeszenszkyoutput: html_document---

```{r setup, include = FALSE}knitr::opts_chunk$set(echo = TRUE)```

# Using LaTeX and R

Plot of the function $f(x) = sin(x) + cos(\sqrt{3}x)$:```{r}library(ggplot2)f

34

35

R Markdown (9)● bookdown:

– R csomag könyvek, nagyobb lélegzetű cikkek és jelentések R Markdown formátumban történő elkészítéséhez.

– Többféle kimeneti formátumot támogat: PDF, LaTeX, HTML, EPUB, MS Word.

– Lehetővé teszi dinamikus grafika és interaktív alkalmazások beillesztését is.

– Valamennyi kimeneti formátumhoz lehetővé teszi LaTeX matematikai formulák használatát.

– A bookdown-nal készült könyvek listáját lásd a csomag webhelyén.– Webhely: https://bookdown.org/– Dokumentáció: https://bookdown.org/yihui/bookdown/

https://bookdown.org/https://bookdown.org/yihui/bookdown/

36

Mintapéldák

● https://github.com/jeszy75/markdown-examples

https://github.com/jeszy75/markdown-examples

37

További olvasnivaló

● Sean Leonard. Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations. RFC 7764. March 2016. https://tools.ietf.org/html/rfc7764

https://tools.ietf.org/html/rfc7764

Dia 1Dia 2Dia 3Dia 4Dia 5Dia 6Dia 7Dia 8Dia 9Dia 10Dia 11Dia 12Dia 13Dia 14Dia 15Dia 16Dia 17Dia 18Dia 19Dia 20Dia 21Dia 22Dia 23Dia 24Dia 25Dia 26Dia 27Dia 28Dia 29Dia 30Dia 31Dia 32Dia 33Dia 34Dia 35Dia 36Dia 37