Documenting Tools: Markdown

An introduction to Markdown and related software by Dr. Yi-Xin Liu at Fudan University (lyx@fudan.edu.cn).

This is a part of the course: Road to Scientific Research: Powerful Computer Applications (XDSY118019.01).

Lecture date: 2023.11.02

What is Markdown?

Markdown is a lightweight markup language for creating formatted text using a plain-text editor.

  • John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form.
  • Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions, unlike text formatted with ‘heavier’ markup languages, such as Rich Text Format (RTF), HTML, and XML.
  • Markdown file often ends with extension .md.

What is it used for?

  • README files and software documentation (Github, etc.)
  • Programming notebook systems (Jupyter notebook, etc.)
  • Forum & blog posts (Discourse, Zhihu, etc.)
  • Static site generators (Jekyll, etc.)
  • Note taking software (Obsidian, etc.)
  • Slideshow (Marp, etc.)

Things you can format

  • Headings
  • Lists: unordered, ordered, nested
  • Emphasis: italic, bold, strikethrough
  • Links
  • Images
  • Blockquote
  • Horizontal rules
  • Footnote
  • Blocks of code*, Blocks of math expressions*, Task lists*, Table*

*: GFM and other Markdown variants

Demo and exercises of Markdown

  • Go to VS Code and follow demonstration there.

What is Obsidian?

Obsidian a powerful knowledge base on top of
a local folder of plain text Markdown files. It is a note taking software. And it is completely FREE!

Features of Obsidian:

  • Everything is connected: backlinks, outgoing links, graph view
  • Extensively extensible: plugins, themes, and custom CSS.
  • Notes for your grandchildren: future-proof format, total control, always available.

Obsidian is branded as

A second brain for you, forever.

Getting started with Obsidian

Demo and exercises of Obsidian

What is Marp?

Marp (also known as the Markdown Presentation Ecosystem) provides an intuitive experience for creating beautiful slide decks. You only have to focus on writing your story in a Markdown document.

All slides in this course are made using Marp!

Features of Marp:

  • Based on CommonMark
  • Built-in themes and CSS theming
  • Directives and extended syntax
  • Export to HTML, PDF, and PowerPoint
  • Full open-source and FREE.

Demo and exercises of Marp

  • Install the Marp extension for VS Code.
  • Follow the demonstration.