Markdown Overview Quiz

Markup Languages

• Markup languages are computer languages used to annotate text.
• They link metadata to parts of text in a clear, distinct 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/

What is Markdown?

• Markdown is a lightweight markup language.
• It uses plain text formatting syntax.
• See: https://en.wikipedia.org/wiki/Markdown

Symbol

• The Markdown Mark, by Dustin Curtis, is a capital "M" with a downward-pointing arrow.
• Source: https://dcurt.is/the-markdown-mark
• Source: https://github.com/dcurtis/markdown-mark

Characteristics

• Markdown is easy to read and write, using plain text.
• It converts to various formats (e.g., HTML).
• It is targeted at non-technical users.
• Its syntax is inspired by plain text email.

Usage (1)

• Markdown is frequent on the web for entering text.
• Key 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

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

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/

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?

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

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

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: 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/

Usage (8)

• Data science tools:
  • Project Jupyter: See: Markdown Cells

Usage (9)

• AI tools:
  • 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

History (1)

• Markdown was developed in 2004 by John Gruber with contributions from Aaron Swartz.
• It was created as a plain text format for writing structured documents.
• A Perl script converted Markdown to HTML (Markdown.pl).
• Website: https://daringfireball.net/projects/markdown/

History (2)

• John Gruber's motivation behind Markdown, in a 2004 article: https://daringfireball.net/2004/03/dive_into_markdown

• The original Markdown syntax: https://daringfireball.net/projects/markdown/syntax

• Markdown syntax is not completely unambiguous.

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

Syntactic Ambiguities (1)

• See CommonMark Spec for a full list of syntactic ambiguities.

• Why a spec is needed.

• A method to address ambiguity is to examine Gruber's implementation (Markdown.pl)

• Unfortunately, it was quite buggy.

Syntactic Ambiguities (2)

• Babelmark 3 (https://babelmark.github.io/) is a tool to compare outputs of different Markdown implementations.

Standardization

• CommonMark (https://commonmark.org/) is a standard for Markdown syntax.
• Unambiguous specification: https://spec.commonmark.org/
• Validation test suite for implementations: https://spec.commonmark.org/

Variants

• GitHub-flavored Markdown (GFM)
  • See: GitHub Flavored Markdown Spec
• Pandoc's Markdown
  • See: Pandoc User's Guide – Pandoc's Markdown
• Markdown Variants (IANA)

Coding Style

• See: Markdown style guide (Google)

Tutorials

• Markdown Guide: https://www.markdownguide.org/ https://github.com/mattcone/markdown-guide
• Markdown Tutorial (CommonMark)

Editors (1)

• 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?itemName=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

Editors (2)

• 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

Editors (3)

• 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

Editors (4)

• IntelliJ IDEA: Supported in both Ultimate and Community Editions.
• See: https://www.jetbrains.com/help/idea/markdown.html

Conversion Tools

• 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 to another.

• Supports Markdown as both source and target formats.

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 - output.html -c style.css

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 reused.

Pandoc (3)

• Examples of custom CSS stylesheets:
• Pan Am: https://benjam.info/pan-am/ https://github.com/bgw/pan-am
• Tufte: https://jez.io/tufte-pandoc-css/ https://github.com/jez/tufte-pandoc-css
• Pandoc Markdown CSS Theme: https://jez.io/pandoc-markdown-css-theme/ https://github.com/jez/pandoc-markdown-css-theme

Pandoc (4)

• IDE integration (Visual Studio Code):
• vscode-pandoc https://github.com/chrischinchilla/vscode-pandoc https://marketplace.visualstudio.com/items?itemName=ChrisC

Mermaid (1)

• Website: http://mermaid.js.org/
• Repository: https://github.com/mermaid-js/mermaid
• Written in: JavaScript
• License: MIT License

Mermaid (2)

• Supported diagram types: flowchart, sequence, class, state, ER, user journey, Gantt, pie chart, requirement (SysML), Git graph,
• Supported output formats: PDF, PNG, SVG
• Mermaid diagrams can be embedded in Markdown documents.

Mermaid (3)

• Tool support:
  • Live editor: https://mermaid.live/edit
  • GitHub support: Embed diagrams in Markdown files using Mermaid.
  • Visual Studio Code: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid
  • Command-line interface: https://github.com/mermaid-js/mermaid-cli https://github.com/raghur/mermaid-filter

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]

Mermaid (5)

• Diagram representation of the flowchart example: (Image of the flowchart, see the original document)

Mermaid (6)

• Embedding diagrams in Markdown documents (GitHub, Pandoc):

## Mermaid diagram

• Pandoc requires the --filter mermaid-filter command-line option.

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/