Introduction to

Wei Min Cher

09 January 2020

Contents

• Markdown
• GitHub Flavored Markdown
• Typora
• Pandoc
• Mkdocs

Markdown

• Lightweight markup language
• Can be converted to many formats

GitHub Flavored Markdown

Markdown Editor

• GitHub Gist
• Stackedit.io

Headers

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

This is an h1 tag

This is an h2 tag

This is an h6 tag

Emphasis

*This will be italic* _This will also be italic_

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


_You **can** combine them_

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

Unordered Lists

* Item 1
* Item 2
  * Item 2a
  * Item 2b

• Item 1
• Item 2
  • Item 2a
  • Item 2b

Ordered Lists

1. Item 1
2. Item 2
3. Item 3
  i. Item 3a
  ii. Item 3b

1. Item 1
2. Item 2
3. Item 3
   i. item 3a
   ii. item 3b

Links

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

http://github.com
GitHub

Images

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

Tables

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column

Activity 1 (10 mins)

• Make a to-do list with 3 categories
  1. To do
  2. In progress
  3. Done

#### To do

1. Pray for good fortune

- Temple
- Bell curve god

##### In progress

1. Catching up on **_SLEEP_**

###### Done

1. School

To do

1. Pray for good fortune

• Temple
• Bell curve god

In progress

1. Catching up on SLEEP

Done

1. School

Inline code

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

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

Syntax highlighting

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

```python
def foo():
    if not bar:
        return True
```

Blockquotes

As Kanye West said:

> We're living the future so the present is our past.

Works with HTML.

Typora

http://typora.io/

Inline Math

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

$$ e = mc^2$$

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

Introduction to $\LaTeX$

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


Sign up here.

Diagrams

UML Sequence

js-sequence

```sequence
Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!

​```

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
​```

Mermaid

mermaid-js

Class Diagram

```mermaid
classDiagram
      Animal <|-- Duck
      Animal <|-- Fish
      Animal <|-- Zebra
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()

      class Duck{
          +String beakColor
          +swim()
          +quack()
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
          +bool is_wild
          +run()
      }

State Diagram

```mermaid
stateDiagram
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

Pie Chart

```mermaid
pie
    title Pie Chart
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 150
```

Pandoc

Swiss-army knife to convert content

Conversion between

• PDF
• Markup formats
• HTML formats
• Ebooks
• XML formats
• $\TeX$ formats
• Word processor formats
• Interactive notebook formats
  $\cdots$

Demo

Converting Markdown to HTML

MkDocs

Project documentation with Markdown.

Installing MkDocs

pip install mkdocs

Material theme for MkDocs

pip install mkdocs-material

Create a new site

• cd to the appropriate folder

mkdocs new my-project
cd my-project

Editing mkdocs.yml

site_name: Test
nav:
  - Home: index.md
  - About: about.md
theme:
  name: "material"

Serving the site

mkdocs serve

• Site up at localhost:8000

Activity 2 (15 min)

• Play around with the Material themed site
• Refer to Getting Started for more customization

Building the site

mkdocs build

• By default, files at /site

Free web hosting for GitHub users

Personal Sites

• at username.github.io
• Repository should be 'username.github.io'
• Source: master branch
  • Contents of \site to be placed here

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

Activity 3 (5 mins)

Host the website on GitHub.

Powered by

Markdown Presentation Ecosystem

This entire slide deck was done entirely in Markdown.

Source Code

OpenSUTD / IAP2020-MkDocs

OpenSUTD

An open organisation owned
by the SUTD community.

Signing off,

@flamanta