Markdown Presentation PDF

Markdown Péter Jeszenszky September 20, 2024 Péter Jeszenszky Markdown September 20, 2024 1 / 39 Markup Languages Markup languages are computer languages for annotating text. They allow the association of metadata with parts of text i...

Markdown Péter Jeszenszky September 20, 2024 Péter Jeszenszky Markdown September 20, 2024 1 / 39 Markup Languages Markup languages are computer languages for annotating text. They allow the association of metadata with parts of text in a clearly distinguishable way. Examples: AsciiDoc https://asciidoc.org/ Markdown https://daringfireball.net/projects/markdown/ TeX, LaTeX https://www.latex-project.org/ troff (man pages) https://www.gnu.org/software/groff/ Wikitext https://en.wikipedia.org/wiki/Help:Wikitext XML https://www.w3.org/XML/ Péter Jeszenszky Markdown September 20, 2024 2 / 39 What is Markdown? Markdown is a lightweight markup language with plain text formatting syntax. See: https://en.wikipedia.org/wiki/Markdown Péter Jeszenszky Markdown September 20, 2024 3 / 39 Symbol Dustin Curtis. The Markdown Mark. https://dcurt.is/the-markdown-mark https://github.com/dcurtis/markdown-mark Figure 1: The Markdown Mark Péter Jeszenszky Markdown September 20, 2024 4 / 39 Characteristics An easy-to-read and easy-to-write plain text format. Can be converted to various output formats (e.g., HTML). Specifically targeted at non-technical users. The syntax is mostly inspired by the format of plain text email. Péter Jeszenszky Markdown September 20, 2024 5 / 39 Usage (1) Markdown is widely used on the web for entering text. The main application areas include: Collaboration platforms and tools Blogging platforms and content management systems Online community platforms Note-taking applications Technical and scientific publishing Presentation authoring Data science tools AI tools Péter Jeszenszky Markdown September 20, 2024 6 / 39 Usage (2) Collaboration platforms and tools: GitHub: See: Writing on GitHub Microsoft Teams: See: Use Markdown formatting in Teams Trello: See: How To Format Your Text in Trello Péter Jeszenszky Markdown September 20, 2024 7 / 39 Usage (3) Blogging platforms and content management systems: Moodle: See: https://docs.moodle.org/en/Markdown WordPress: See: https://wordpress.com/support/wordpress- editor/blocks/markdown-block/ Péter Jeszenszky Markdown September 20, 2024 8 / 39 Usage (4) Online community platforms: Discord: See: Markdown Text 101 (Chat Formatting: Bold, Italic, Underline) Reddit: See: https://www.reddit.com/wiki/markdown/ Stack Overflow: See: How do I format my posts using Markdown or HTML? Péter Jeszenszky Markdown September 20, 2024 9 / 39 Usage (5) Note-taking applications: Joplin (platform: Linux, macOS, Windows, Android, iOS; written in: TypeScript; license: AGPLv3) https://joplinapp.org/ https://github.com/laurent22/joplin memos (platform: Docker; written in: Go, TypeScript; license: MIT License) https://www.usememos.com/ https://github.com/usememos/memos Péter Jeszenszky Markdown September 20, 2024 10 / 39 Usage (6) Technical and scientific publishing: bookdown https://bookdown.org/ https://github.com/rstudio/bookdown Daniel Stenberg. Everything curl. https://everything.curl.dev/ https://github.com/curl/everything-curl GitBook: See: https://docs.gitbook.com/content-creation/editor/markdown Microsoft Learn: See: Markdown reference for Microsoft Learn Péter Jeszenszky Markdown September 20, 2024 11 / 39 Usage (7) Presentation authoring: Marp: Markdown Presentation Ecosystem (platform: browser; written in: TypeScript; license: MIT License) https://marp.app/ https://github.com/marp-team/marp Visual Studio Code extension: Marp for VS Code https://marketplace.visualstudio.com/items?itemName=marp- team.marp-vscode https://github.com/marp-team/marp-vscode remark (platform: browser; written in: JavaScript; license: MIT License) https://github.com/gnab/remark https://remarkjs.com/ reveal.js (platform: browser; written in: JavaScript; license: MIT License) https://revealjs.com/ https://github.com/hakimel/reveal.js Markdown support: https://revealjs.com/markdown/ Péter Jeszenszky Markdown September 20, 2024 12 / 39 Usage (8) Data science tools: Project Jupyter: See: Markdown Cells Péter Jeszenszky Markdown September 20, 2024 13 / 39 Usage (9) Many AI tools provide support for Markdown, see, for example: ChatGPT (OpenAI): See: Aneesha Bakharia. ChatGPT and Markdown formats – Generating all Sorts of Editable Diagrams and Formats. January 11, 2023. Gemini (Google): See: https://ai.google.dev/gemini-api/docs/file-prompting-strategies Péter Jeszenszky Markdown September 20, 2024 14 / 39 History (1) Originally, Markdown was developed in 2004 by John Gruber with contributions from Aaron Swartz. It was a created in the form of: a plain text format for writing structured documents, and a Perl script to convert Markdown to HTML (Markdown.pl). Website: https://daringfireball.net/projects/markdown/ Péter Jeszenszky Markdown September 20, 2024 15 / 39 History (2) About the motivation behind the creation of Markdown: John Gruber. Dive Into Markdown. 19 March 2004. https://daringfireball.net/2004/03/dive_into_markdown The original Markdown syntax: https://daringfireball.net/projects/markdown/syntax The syntax is not specified unambiguously. Péter Jeszenszky Markdown September 20, 2024 16 / 39 File Properties File extension:.md Media type: text/markdown Optional parameter: variant See: Sean Leonard. The text/markdown Media Type. RFC 7763. March 2016. https://www.rfc-editor.org/rfc/rfc7763 Péter Jeszenszky Markdown September 20, 2024 17 / 39 Syntactic Ambiguities (1) For a comprehensive list of syntactic ambiguities, see: CommonMark Spec – Why is a spec needed? A possible option to resolve these ambiguities is to consult the source code of Gruber’s implementation (i.e., Markdown.pl). Unfortunately, it was quite buggy. Péter Jeszenszky Markdown September 20, 2024 18 / 39 Syntactic Ambiguities (2) Babelmark 3 https://babelmark.github.io/ A tool for comparing the output of various implementations of the original Markdown syntax. Péter Jeszenszky Markdown September 20, 2024 19 / 39 Standardization CommonMark https://commonmark.org/ A standard, unambiguous syntax specification for Markdown. Specification: https://spec.commonmark.org/ Provides a test suite to validate implementations against the specification. Péter Jeszenszky Markdown September 20, 2024 20 / 39 Variants Several variants and extensions of Markdown exist, for example: GitHub Flavored Markdown (GFM) See: GitHub Flavored Markdown Spec Pandoc’s Markdown See: Pandoc User’s Guide – Pandoc’s Markdown … See: Markdown Variants (IANA) Péter Jeszenszky Markdown September 20, 2024 21 / 39 Coding Style See: Markdown style guide (Google) Péter Jeszenszky Markdown September 20, 2024 22 / 39 Tutorials Markdown Guide https://www.markdownguide.org/ https://github.com/mattcone/markdown-guide Markdown Tutorial (CommonMark) Péter Jeszenszky Markdown September 20, 2024 23 / 39 Editors (1) Free and open source software: Visual Studio Code (platform: Linux, macOS, Windows; license: MIT License) https://code.visualstudio.com/ https://github.com/Microsoft/vscode See: https://code.visualstudio.com/docs/languages/markdown Recommended extensions: Markdown All in One https://marketplace.visualstudio.com/items?ite mName=yzhang.markdown-all-in-one https://github.com/yzhang-gh/vscode-markdown markdownlint https://marketplace.visualstudio.com/items?itemName= DavidAnson.vscode-markdownlint https://github.com/DavidAnson/vscode-markdownlint Markdown+Math https: //marketplace.visualstudio.com/items?itemName=goessner.mdmath https://github.com/goessner/mdmath Péter Jeszenszky Markdown September 20, 2024 24 / 39 Editors (2) Free and open source software (continued): ghostwriter (platform: Linux, Windows; written in: C++; license: GPLv3) https://ghostwriter.kde.org/ https://github.com/KDE/ghostwriter Mark Text (platform: Linux, macOS, Windows; written in: JavaScript; license: MIT License) https://www.marktext.cc/ https://github.com/marktext/marktext Zettlr (platform: Linux, macOS, Windows; written in: JavaScript; license: GPLv3) https://www.zettlr.com/ https://github.com/Zettlr/Zettlr Péter Jeszenszky Markdown September 20, 2024 25 / 39 Editors (3) Free and open source software (continued): Milkdown (platform: browser; written in: TypeScript; license: MIT License) https://milkdown.dev/ https://github.com/Milkdown/milkdown Demo: https://milkdown.dev/online-demo StackEdit (platform: browser; written in: JavaScript; license: Apache License 2.0) https://stackedit.io/ https://github.com/benweet/stackedit Péter Jeszenszky Markdown September 20, 2024 26 / 39 Editors (4) Non-free software: IntelliJ IDEA: Supported in both Ultimate and Community Editions. See: https://www.jetbrains.com/help/idea/markdown.html Péter Jeszenszky Markdown September 20, 2024 27 / 39 Conversion Tools Free and open source software: Pandoc (platform: Linux, macOS, Windows; license: GPLv2) https://pandoc.org/ https://github.com/jgm/pandoc A command-line tool written in Haskell to convert files from one markup format into another. Markdown is supported both as source and target formats. Péter Jeszenszky Markdown September 20, 2024 28 / 39 Pandoc (1) Installation: https://pandoc.org/installing.html Use: https://pandoc.org/MANUAL.html Generating HTML output: 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 Péter Jeszenszky Markdown September 20, 2024 29 / 39 Pandoc (2) Styling HTML output with CSS: The -c/--css command line option associates a custom CSS stylesheet with the output HTML document. This option can be used repeatedly. Péter Jeszenszky Markdown September 20, 2024 30 / 39 Pandoc (3) Examples of custom CSS stylesheets: Pan Am: Simple CSS for Pandoc (license: WTFPL) https://benjam.info/pan-am/ https://github.com/bgw/pan-am CSS stylesheet: http://benjam.info/panam/styling.css Tufte Pandoc CSS (license: MIT License) https://jez.io/tufte-pandoc-css/ https://github.com/jez/tufte-pandoc-css Pandoc Markdown CSS Theme (license: Blue Oak Model License) https://jez.io/pandoc-markdown-css-theme/ https://github.com/jez/pandoc-markdown-css-theme Péter Jeszenszky Markdown September 20, 2024 31 / 39 Pandoc (4) IDE integration: Visual Studio Code: vscode-pandoc https://github.com/chrischinchilla/vscode-pandoc https://marketplace.visualstudio.com/items?itemName=ChrisChinchill a.vscode-pandoc Péter Jeszenszky Markdown September 20, 2024 32 / 39 Mermaid (1) A diagramming tool inspired by Markdown. Website: http://mermaid.js.org/ Repository: https://github.com/mermaid-js/mermaid Written in: JavaScript License: MIT License Péter Jeszenszky Markdown September 20, 2024 33 / 39 Mermaid (2) Supported diagram types: flowchart, sequence diagram, class diagram, state diagram, ER diagram, user journey diagram, Gantt chart, pie chart, requirement diagram (SysML), Git graph, … Supported output formats: PDF, PNG, SVG Mermaid diagrams can be embedded in Markdown documents. Péter Jeszenszky Markdown September 20, 2024 34 / 39 Mermaid (3) Tool support: Live editor: https://mermaid.live/edit GitHub support: Include diagrams in your Markdown files with Mermaid Visual Studio Code: Markdown Preview Mermaid Support https://marketplace.visualstudio.com/items?itemName=bierner.mark down-mermaid https://github.com/mjbvz/vscode-markdown-mermaid Command-line interface: https://github.com/mermaid-js/mermaid-cli Pandoc: https://github.com/raghur/mermaid-filter For more tools, see: https://mermaid.js.org/ecosystem/integrations-community.html Péter Jeszenszky Markdown September 20, 2024 35 / 39 Mermaid (4) Example: Engineering flowchart flowchart TD A{Does it move?} A -->|No| B{Should it?} A -->|Yes| C{Should it?} B -->|No| D[No problem] B -->|Yes| E[WD-40] C -->|Yes| F[No problem] C -->|No| G[Duct tape] Péter Jeszenszky Markdown September 20, 2024 36 / 39 Mermaid (5) Does it move? No Yes Should it? Should it? No Yes Yes No No problem WD-40 No problem Duct tape Péter Jeszenszky Markdown September 20, 2024 37 / 39 Mermaid (6) Embeddig a diagram in a Markdown document (GitHub, Pandoc): ```mermaid # Mermaid diagram ``` Pandoc must be run with the --filter mermaid-filter command line option that requires the availability of mermaid-filter. Péter Jeszenszky Markdown September 20, 2024 38 / 39 Further Reading Sean Leonard. Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations. RFC 7764. March 2016. https://www.rfc-editor.org/rfc/rfc7764 Knut Sveidqvist, Ashish Jain. The Official Guide to Mermaid.js. Packt Publishing, 2021. https://mermaid.js.org/landing/ Péter Jeszenszky Markdown September 20, 2024 39 / 39