Markdown What is Markdown? ● Markdown is a lightweight markup language with plain text formatting syntax. Péter Jeszenszky – See: https://en.wikipedia.org/wiki/Markdown Faculty of Informatics, University of Debrecen [email protected] Last modified: October 4, 2019 3 Markup Languages Symbol ● Markup languages are computer languages for annotating ● Dustin Curtis. The Markdown Mark. text. https://dcurt.is/the-markdown-mark – They allow the association of metadata with parts of text in a https://github.com/dcurtis/markdown-mark clearly distinguishable way. ● Examples: – TeX, LaTeX https://www.latex-project.org/ – Markdown https://daringfireball.net/projects/markdown/ – troff (man pages) https://www.gnu.org/software/groff/ – XML https://www.w3.org/XML/ – Wikitext https://en.wikipedia.org/wiki/Help:Wikitext 2 4 Characteristics Usage (2) ● An easy-to-read and easy-to-write plain text ● Collaboration platforms and tools: format that. – GitHub https://github.com/ ● Can be converted to various output formats ● See: Writing on GitHub (e.g., HTML). https://help.github.com/en/categories/writing-on-github – Trello https://trello.com/ ● Specifically targeted at non-technical users. ● See: How To Format Your Text in Trello ● The syntax is mostly inspired by the format of https://help.trello.com/article/821-using-markdown-in-trell o plain text email. 5 7 Usage (1) Usage (3) ● Markdown is widely used on the web for ● Blogging platforms and content management entering text. systems: – ● The main application areas include: Ghost https://ghost.org/ ● See: Using Markdown https://ghost.org/faq/using-markdown/ – Collaboration platforms and tools – WordPress https://wordpress.com/ – Blogging platforms and content management ● See: Using Markdown on WordPress.com systems https://en.support.wordpress.com/can-i-use-markdown-on-wor dpress-com/ – Online community platforms – Squarespace https://www.squarespace.com/ – Technical and scientific publishing ● See: Using Markdown Blocks https://support.squarespace.com/hc/en-us/articles/205813788 6 8 Usage (4) History (1) ● Online community platforms: ● Originally, Markdown was developed in 2004 by – reddit https://www.reddit.com/ John Gruber with contributions from Aaron Swartz. ● See: https://www.reddit.com/wiki/markdown – Stack Overflow https://stackoverflow.com/ – It was a created in the form of: ● ● See: How do I format my posts using Markdown or a plain text format for writing structured documents, and HTML? https://stackoverflow.com/help/formatting ● a Perl script to convert Markdown to HTML (Markdown.pl). ● Website: https://daringfireball.net/projects/markdown/ 9 11 Usage (5) History (2) ● Technical and scientific publishing: ● About the motivation behind the creation of – bookdown https://bookdown.org/ Markdown: – Daniel Stenberg. Everything curl. – John Gruber. Dive Into Markdown. 19 March 2004. https://curl.haxx.se/book.html https://daringfireball.net/2004/03/dive_into_markdo https://github.com/bagder/everything-curl wn – GitBook https://www.gitbook.com/ ● The original Markdown syntax: ● See: https://docs.gitbook.com/content-editing/markdown https://daringfireball.net/projects/markdown/synt – Microsoft Docs https://docs.microsoft.com/ ax ● See: How to use Markdown for writing Docs – https://docs.microsoft.com/en-us/contribute/how-to-write-use-m The syntax is not specified unambiguously. arkdown 10 12 File Properties Syntactic Ambiguities (2) ● File extension: .md ● Babelmark 2 https://johnmacfarlane.net/babelmark2/ ● Media type: text/markdown – A tool for comparing the output of various – Optional parameter: variant implementations of the original Markdown syntax. ● See: Sean Leonard. The text/markdown Media Type. RFC 7763. March 2016. https://tools.ietf.org/html/rfc7763 13 15 Syntactic Ambiguities (1) Standardization ● For a comprehensive list of syntactic ● CommonMark https://commonmark.org/ ambiguities, see: – A standard, unambiguous syntax specification for – CommonMark Spec – Why is a spec needed? Markdown. https://spec.commonmark.org/0.29/#why-is-a-spec- – Specification: CommonMark Spec needed- https://spec.commonmark.org/ ● A possible option to resolve these ambiguities is ● Provides a test suite to validate implementations against to consult the source code of Gruber's the specification. implementation (i.e., Markdown.pl). – Unfortunately, it was quite buggy. 14 16 Variants Editors (1) ● Several variants and extensions of Markdown exist, for ● Free and open source software: example: – Atom (platform: Linux, macOS, Windows; license: MIT License) https://atom.io/ https://github.com/atom/atom – GitHub Flavored Markdown (GFM) ● Packages: – Markdown Preview (license: MIT License) https://atom.io/packages/markdown-preview ● See: GitHub Flavored Markdown Spec https://github.github.com/gfm/ https://github.com/atom/markdown-preview – Markdown-Writer (license: MIT License) https://atom.io/packages/markdown-writer – Pandoc's Markdown https://github.com/zhuochun/md-writer – Notepad++ (platform: Windows; license: GPLv2) https://notepad-plus-plus.org/ ● See: Pandoc User’s Guide – Pandoc's Markdown https://github.com/notepad-plus-plus/notepad-plus-plus https://pandoc.org/MANUAL.html#pandocs-markdown ● Plugin: markdown++ (license: MIT License) https://github.com/Edditoria/markdown-plus-plus – … – StackEdit (written in: JavaScript; license: Apache License 2.0) https://stackedit.io/ https://github.com/benweet/stackedit ● See: Markdown Variants – Visual Studio Code (platform: Linux, macOS, Windows; license: MIT License) https://www.iana.org/assignments/markdown-variants/m https://code.visualstudio.com/ https://github.com/Microsoft/vscode arkdown-variants.xhtml ● See: https://code.visualstudio.com/docs/languages/markdown 17 19 Tutorials Editors (2) ● Markdown Guide ● Non-free software: https://www.markdownguide.org/ – <oXygen/> XML Editor https://www.oxygenxml.com/ ● Markdown Tutorial ● See: https://www.oxygenxml.com/xml_editor/markdown_editor. https://commonmark.org/help/tutorial/ html – IntelliJ IDEA https://www.jetbrains.com/idea/ ● Supported in Ultimate and Community Editions. ● See: https://www.jetbrains.com/help/idea/markdown.html 18 20 Conversion Tools Pandoc (2) ● Free and open source software: ● Styling the output with CSS: – Pandoc (platform: Linux, macOS, Windows; license: GPLv2) – The / command line option associates a https://pandoc.org/ https://github.com/jgm/pandoc -c --css custom CSS stylesheet with the output document. ● A command-line tool written in Haskell to convert convert files from one markup format into another. ● This option can be used repeatedly. ● Markdown is supported both as source and target formats. ● Online services: – Docverter (written in: JRuby; license: MIT License) https://www.docverter.com/ https://github.com/docverter/docverter ● A document conversion server with an HTTP API that wraps Pandoc. 21 23 Pandoc (1) Pandoc (3) ● Installation: https://pandoc.org/installing.html ● Examples of custom CSS stylesheets: ● Use: https://pandoc.org/MANUAL.html – Pan Am: Simple CSS for Pandoc (license: WTFPL) https://benjam.info/pan-am/ pandoc --standalone --smart --to html5 input.md \ https://github.com/bgw/pan-am --output output.html --css style.css ● CSS stylesheet: http://benjam.info/panam/styling.css or – Tufte Pandoc CSS (license: MIT License) https://jez.io/tufte-pandoc-css/ pandoc -s -S -t html5 input.md -o output.html \ https://github.com/jez/tufte-pandoc-css -c style.css 22 24 Pandoc (4) R Markdown (2) ● IDE integration: ● R Markdown is implemented as an R package – Visual Studio Code: (rmarkdown). ● vscode-pandoc https://github.com/dfinke/vscode-pandoc https://cran.r-project.org/web/packages/rmarkdo https://marketplace.visualstudio.com/items?itemName=D wn/ ougFinke.vscode-pandoc 25 27 R Markdown (1) R Markdown (3) ● R Markdown is an extension of Markdown that ● Supported output formats: HTML, PDF, PowerPoint, enables the embedding of executable code MS Word, … chunks. ● Creating PDF output requires a TeX installation. – For example, the following languages are – For the list of available options, see: supported: Apache Groovy, Bash, Haskell, Python, https://www.latex-project.org/get/#tex-distributions Scala, SQL, R, … – The easiest way of installing TeX for R users: ● File extension: .Rmd ● TinyTeX https://yihui.name/tinytex/ – A lightweight, cross-platform, portable TeX distribution based on TeX Live. ● Website: https://rmarkdown.rstudio.com/ – The tinytex R package is provided for installing TinyTeX. The installation does not require administrator privileges. 26 28 R Markdown (4) R Markdown (6) ● Documentation: ● Conversion: – Yihui Xie, J. J. Allaire, Garrett Grolemund. R file.doc Markdown: The Definitive Guide. 2019. https://bookdown.org/yihui/rmarkdown/ https://github.com/rstudio/rmarkdown-book ● Tool support: file.Rmd knitr file.md pandoc file.html – RStudio https://www.rstudio.com/ file.pdf 29 31 R Markdown (5) R Markdown (7) ● --- The rmarkdown packages depends on the title: "R Markdown Example" author: Péter Jeszenszky knitr package. output: html_document --- – knitr is an R package for dynamic report ```{r setup, include = FALSE} generation. knitr::opts_chunk$set(echo = TRUE) – It is used to evaluate computer code embedded in ``` Markdown and to include the result. # Using LaTeX and R – Website: https://yihui.name/knitr/ Plot of the function $f(x) = sin(x) + cos(\sqrt{3}x)$: ```{r} https://github.com/yihui/knitr library(ggplot2) f <- function(x) sin(x) + cos(sqrt(3) * x) ggplot(data.frame(x = 0), aes(x)) + stat_function(fun = f, colour = "blue")
Details
-
File Typepdf
-
Upload Time-
-
Content LanguagesEnglish
-
Upload UserAnonymous/Not logged-in
-
File Pages9 Page
-
File Size-