Introduction to




Wei Min Cher

09 January 2020

Contents

  • Markdown
  • GitHub Flavored Markdown
  • Typora
  • Pandoc
  • Mkdocs
IAP 2020: Introduction to Markdown and MkDocs

invert width:300px

Markdown

  • Lightweight markup language
  • Can be converted to many formats
IAP 2020: Introduction to Markdown and MkDocs

GitHub Flavored Markdown

IAP 2020: Introduction to Markdown and MkDocs

Markdown Editor

  • GitHub Gist
  • Stackedit.io
IAP 2020: Introduction to Markdown and MkDocs

Headers


# This is an h1 tag
## This is an h2 tag
###### This is an h6 tag

IAP 2020: Introduction to Markdown and MkDocs

This is an h1 tag

This is an h2 tag

This is an h6 tag
IAP 2020: Introduction to Markdown and MkDocs

Emphasis


*This will be italic* _This will also be italic_

**This will be bold** __This will also be bold__


_You **can** combine them_

IAP 2020: Introduction to Markdown and MkDocs

This will be italic This will also be italic
This will be bold This will also be bold
You can combine them

IAP 2020: Introduction to Markdown and MkDocs

Unordered Lists

* Item 1
* Item 2
  * Item 2a
  * Item 2b
IAP 2020: Introduction to Markdown and MkDocs
  • Item 1
  • Item 2
    • Item 2a
    • Item 2b
IAP 2020: Introduction to Markdown and MkDocs

Ordered Lists

1. Item 1
2. Item 2
3. Item 3
  i. Item 3a
  ii. Item 3b
IAP 2020: Introduction to Markdown and MkDocs
  1. Item 1
  2. Item 2
  3. Item 3
    i. item 3a
    ii. item 3b
IAP 2020: Introduction to Markdown and MkDocs

Links


http://github.com
[GitHub](http://github.com)

IAP 2020: Introduction to Markdown and MkDocs

http://github.com
GitHub

IAP 2020: Introduction to Markdown and MkDocs

Images


![SUTD Logo](https://www.sutd.edu.sg/assets/sutd/img/logo-white.png)

IAP 2020: Introduction to Markdown and MkDocs

IAP 2020: Introduction to Markdown and MkDocs

Tables

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column
IAP 2020: Introduction to Markdown and MkDocs

IAP 2020: Introduction to Markdown and MkDocs

Activity 1 (10 mins)

  • Make a to-do list with 3 categories
    1. To do
    2. In progress
    3. Done
IAP 2020: Introduction to Markdown and MkDocs
#### To do
1. Pray for good fortune
- Temple
- Bell curve god
##### In progress
1. Catching up on **_SLEEP_**
###### Done
1. School
IAP 2020: Introduction to Markdown and MkDocs

To do

  1. Pray for good fortune
  • Temple
  • Bell curve god
In progress
  1. Catching up on SLEEP
Done
  1. School
IAP 2020: Introduction to Markdown and MkDocs

Inline code

I think you should use an `<addr>` element here instead.
IAP 2020: Introduction to Markdown and MkDocs

I think you should use an <addr> element here instead.

IAP 2020: Introduction to Markdown and MkDocs

Syntax highlighting

```javascript
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}

```python
def foo():
    if not bar:
        return True
```
IAP 2020: Introduction to Markdown and MkDocs

Blockquotes


As Kanye West said:
> We're living the future so the present is our past.
IAP 2020: Introduction to Markdown and MkDocs

IAP 2020: Introduction to Markdown and MkDocs

saturate:5.0 contrast: 100% height:300px drop-shadow:0,5px,10px,rgba(255,255,255)

Works with HTML.

IAP 2020: Introduction to Markdown and MkDocs

Typora

http://typora.io/

IAP 2020: Introduction to Markdown and MkDocs

Inline Math


The identity matrix is $\left[\begin{array}{cc}
1 & 0\\0 & 1\end{array}\right]$.
$$ e = mc^2$$
IAP 2020: Introduction to Markdown and MkDocs

The identity matrix is [1001]\left[\begin{array}{cc}1 & 0\\0 & 1\end{array}\right].

e=mc2e = mc^2

IAP 2020: Introduction to Markdown and MkDocs

Introduction to LaTeX\LaTeX

20 January 2020 (Monday)
TT16 (2.201)
7 - 10 pm


Sign up here.

IAP 2020: Introduction to Markdown and MkDocs

Diagrams

IAP 2020: Introduction to Markdown and MkDocs

UML Sequence

js-sequence


```sequence
Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!
​```
IAP 2020: Introduction to Markdown and MkDocs

UML sequence

IAP 2020: Introduction to Markdown and MkDocs

Flowchart

flowchart.js

```flow
st=>start: Start
op=>operation: Your Operation
cond=>condition: Yes or No?
e=>end
st->op->cond
cond(yes)->e
cond(no)->op
​```
IAP 2020: Introduction to Markdown and MkDocs

width:800px

IAP 2020: Introduction to Markdown and MkDocs

Mermaid

mermaid-js

IAP 2020: Introduction to Markdown and MkDocs

Class Diagram


```mermaid
classDiagram
      Animal <|-- Duck
      Animal <|-- Fish
      Animal <|-- Zebra
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()
IAP 2020: Introduction to Markdown and MkDocs
      class Duck{
          +String beakColor
          +swim()
          +quack()
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
          +bool is_wild
          +run()
      }
IAP 2020: Introduction to Markdown and MkDocs

height:500px

IAP 2020: Introduction to Markdown and MkDocs

State Diagram


```mermaid
stateDiagram
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```
IAP 2020: Introduction to Markdown and MkDocs

height:600px

IAP 2020: Introduction to Markdown and MkDocs

Pie Chart


```mermaid
pie
    title Pie Chart
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 150
```
IAP 2020: Introduction to Markdown and MkDocs

height:500px

IAP 2020: Introduction to Markdown and MkDocs

Pandoc

Swiss-army knife to convert content

IAP 2020: Introduction to Markdown and MkDocs

Conversion between

  • PDF
  • Markup formats
  • HTML formats
  • Ebooks
  • XML formats
  • TeX\TeX formats
  • Word processor formats
  • Interactive notebook formats
    ⋯\cdots
IAP 2020: Introduction to Markdown and MkDocs

Demo

Converting Markdown to HTML

IAP 2020: Introduction to Markdown and MkDocs

MkDocs

Project documentation with Markdown.

IAP 2020: Introduction to Markdown and MkDocs

Installing MkDocs


pip install mkdocs
IAP 2020: Introduction to Markdown and MkDocs

Material theme for MkDocs


pip install mkdocs-material
IAP 2020: Introduction to Markdown and MkDocs

Create a new site

  • cd to the appropriate folder
mkdocs new my-project
cd my-project
IAP 2020: Introduction to Markdown and MkDocs

Editing mkdocs.yml


site_name: Test
nav:
  - Home: index.md
  - About: about.md
theme:
  name: "material"
IAP 2020: Introduction to Markdown and MkDocs

Serving the site


mkdocs serve
  • Site up at localhost:8000
IAP 2020: Introduction to Markdown and MkDocs

Activity 2 (15 min)

  • Play around with the Material themed site
  • Refer to Getting Started for more customization
IAP 2020: Introduction to Markdown and MkDocs

Building the site


mkdocs build
  • By default, files at /site
IAP 2020: Introduction to Markdown and MkDocs

Free web hosting for GitHub users

IAP 2020: Introduction to Markdown and MkDocs

Personal Sites

  • at username.github.io
  • Repository should be 'username.github.io'
  • Source: master branch
    • Contents of \site to be placed here
IAP 2020: Introduction to Markdown and MkDocs

Project Sites

  • at username.github.io/project
  • Repository can have any name
  • Source: master branch /docs folder
    • Contents of \site to be placed inside /docs
IAP 2020: Introduction to Markdown and MkDocs

Activity 3 (5 mins)

Host the website on GitHub.

IAP 2020: Introduction to Markdown and MkDocs

Powered by

saturate:2.0 contrast: 100% height:100px drop-shadow:0,5px,10px,rgba(255,255,255)
Markdown Presentation Ecosystem

IAP 2020: Introduction to Markdown and MkDocs

This entire slide deck was done entirely in Markdown.

IAP 2020: Introduction to Markdown and MkDocs

Source Code


invert height:300px

OpenSUTD / IAP2020-MkDocs

IAP 2020: Introduction to Markdown and MkDocs

OpenSUTD


An open organisation owned
by the SUTD community.

IAP 2020: Introduction to Markdown and MkDocs

Signing off,


@flamanta

IAP 2020: Introduction to Markdown and MkDocs