Markdown & Github

By Yu-Chi Lai

Index

Markdown

易讀、易寫的標記語言

什麼是 Markdown?

  • 由 John Gruber 於 2004 年開發的一款輕量式標記語言
  • 簡單、可讀性高
  • 只需使用標點符號等純文字的形式編寫文件,卻可以轉為  有效的 HTML 格式

markdown 特色

  • 較 word、LibreOffice 等文件編輯器的操作簡單。
  • 許多部落格框架 (如: Hexo)、通訊軟體 (Line、DC)、筆記工具 (Notion..)都有支援 markdown
  • 支援圖片、數學式、程式等區塊的顯示,因而利於專案說明文件的撰寫 (像是 Github 的 README.md)

線上

  • HackMD
  • StackEdit
  • 除了上述,其它網頁基本上都很難用

本機

  • VScode  (可以安裝具有Preview、轉 pdf/html 等功能的插件)
  • Typora
  • Atom
  • Ulysses、iAwriter、Mou、Marxico...etc

編輯器?

HackMD

  • HackMD 是一個跨平台的 Markdown 協作知識庫
  • 有很多神奇操作,像是製作簡報 (Reveal.js style)、書本 (作為多篇筆記的匯集)、自訂範本/主題等
  • 支援 UML、Mathjax、YAML 等語法,可以寫出蠻美觀的圖表、\(LaTeX\) (?
  • 利用留言、共用筆記等方式,可與團隊協作筆記,相當方便
  • 線上、(大部分功能)免費,不香嗎?

介面

編輯/兩側/檢視模式

透過檢視模式,我們可以看到在編輯區的即時更動

範本/由 Github 匯入

語法教學 & 實作

基礎的應用

基本排版

標題
# 第一層級標題
## 第二層級標題
### 第三層級標題
#### 第四層級標題
##### 第五層級標題
###### 第六層級標題
引用區塊
> 引用區塊
>> 子引用區塊
>>> 子子引用區塊
>>>> 子子子引用區塊
**AAA** 粗體
*AAA* 斜體
~~AAA~~ 刪除線
19^th^ 上標
H~2~O 下標
++AAA++ 底線
==AAA== 標記文字
<font color="blue">插入html 標籤,
    透過屬性幫字體變色</font>

項目符號

+ 無序項目 (也可以用`*`跟`-`)
1. 項目一
2. 項目二
    1. 子項目
    2. 7122 
+ 項目
    + 子項目
        + 子子項目

圖片 & 超連結

[顯示文字](通往的連結)
[Useful Resources](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

![圖片說明](圖片連結)
![](https://i.imgur.com/vCeJSXY.jpg =200x200)

色塊強調

:::success
綠色區塊
## 也可以打標題
~~字體變化~~
:::
:::info
藍色區塊
:::
:::warning
黃色區塊
:::
:::danger
可能是紅色區塊
:::
:::spoiler
防爆雷區塊
:::

建立表格

|姓名|職位|專長|綽號|
|---|---|---|---|
|詹喆惟|社長|女裝、裝弱|吉吉|
|陳泓宇|副社/學術|~~盜帳~~、Python|皓亦(?|
|鯊魚抱枕|吉祥物|躺沙發|鯊鯊

Math

例如: $ax^2+bx+c=0、$
$$
\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}
$$
$$
\int_{a}^{b} x^2 dx=\frac{1}{3}x^3|_{a}^{b}
$$

Code

```python=
import os
import shutil
for folder_name in os.listdir("."):
    for file_name in os.listdir(f'.\\{folder_name}'):
        source = ".\\"+folder_name+"\\"+file_name
        destination = ".\\data\\"+folder_name+"_"+file_name
        shutil.copy(source,destination)
        print("copied",folder_name+"_"+file_name)
```

行內要打程式碼? 在文字外包著 `` 吧

製作簡報

---
title: 範例簡報        # 簡報的名稱
type: slide # 讓他可以直接預覽
tags: presentation   # 簡報的標籤
slideOptions:        # 簡報相關的設定
  theme: solarized   # 顏色主題
  transition: 'fade' # 換頁動畫
---
# 章節 1

---

# 章節 2

----

## 章節 2.1

----

## 章節 2.2

---

# 章節 3

先以YAML自訂簡報選項,再透過 ---、----分別隔開標題頁/分頁

Git & Github

版本控制系統?

版本控制系統

  • 讓每位成員的軟體版本可以方便同步和維護管理
  • 可以分為分散式及中央式系統
  • 中央式系統只利用一台伺服器來維護專案,且一次只由一位開發者管理、由總管理者為檔案上鎖(?,EX: Subversion、CVS
  • 分散式則允許多個開發者一同管理,也具有合併各版本變更的功能,自由度與穩定度較高。EX: Git、Bitkeeper

Git、Github

  • Git 是一個分散式版本控制系統,最初是由 Linux Torvalds 所創作,一開始是用來改善 Linux Kernel 開發的管理,而 Git 具備良好的合併程式碼功能。
  • Github 是一個支援 Git 程式碼存取及遠端託管的平台,許多開源的專案皆使用 Github 進行程式碼之管理
  • 基本上 Github 就是工程師最大的開源社群,不論是想協作、交流程式碼都可以

Git 基本觀念

  • 可以分為 Local 和 Remote 兩個環境
  • 可以在 local 環境下開發,等到有網路時再將自己的程式推到 Remote 環境或 pull 下其他開發者程式碼進行整合。
  • Local 中我們又分為 working directory、staging area 和 repositories。
  • 進入檔案庫之前會先將檔案加入暫存區,確認沒問題則 commit 到檔案庫中,最後 push 上去 remote 環境。
  • 協作時必須處理不同 branch 之間 conflict 和 merge 的問題。

註冊 Github

建立 Repo (專案儲存庫)

管理專案開發

Issue: Bug 回報、新功能公布等協助開發者管理專案的訊息

Pull request: 要求其它協作者將自己的程式碼納入專案中

環境架設

Linux: 

$ apt-get install git 或是 yum install gitcore

Windows: Github Desktop!

雖然 Git 有許多 GUI 的軟體,但建議一開始還是使用 CLI 的方式熟悉 git

 安裝完後在終端機打git --version應該就有東西了

基礎指令應用 & 實作

讓 Github 成為你的助手吧

建立本機的 Repository

// 建立一個 hello-git 資料夾
 $ mkdir hello-git
 // 移動到 hello-git 資料夾
 $ cd hello-git
 // 將專案資料夾建立成 git repository
 $ git init
 // 列出專案資料夾下的檔案和資料夾(-l 參數為列出詳細資料,-a 為列出隱藏資料夾)
 $ ls -la
$ git config --global user.name "<Your Name>"
$ git config --global user.email "<your@gmail.com>"

讓電腦知道之後的修改要連結到誰、哪個信箱

創建資料夾、初始化

檢視狀態、新增/修改 commit

$ git status
 On branch master

 Initial commit
 ...
 // 將 git 加入追蹤範圍中/暫存區
 $ git add hello.py
 $ git status
 On branch master
 Initial commit
 ...
// 比較現在檔案和上次 commit 之間的差異,也就是說你做了哪些修改
 $ git diff
 // -m 為輸入 commit message,也就是說這個 commit 內做了哪些事情
 $ git commit -m "Init hello.py"
 [master (root-commit) ad6d328] Init hello.py
 1 file changed, 1 insertion(+)
 create mode 100644 hello.py

把你的專案放到 Github 上吧

先建立一個 repo ,把 git 的網址 copy 下來

 // 本地端專案知道 origin 對應到遠端網址
 $ git remote add origin <remote的網址>
 // 將檔案 push 到遠端的資料庫
 $ git push -u origin main

參數 -u 等同於 --set-upstream,設定 upstream 可以使分支開始追蹤指定的遠端分支

補充-名詞解釋

  • .gitignore: 忽略的檔案清單,這是用來告訴 Git,當在做版本控制記錄的時候,忽略這些檔案。
    不然你可能會在寫 discord bot 時把 bot token 洩漏
  • README.md: repository 介紹和使用方式說明(例如:使用方法、參與專案方式等),以 markdown 撰寫。
  • LICENSE: 專案使用何種授權方式,例如:MIT、BSD 等

\(The\ End\)

\(Thanks\ for\ your\ listening\!\)

 

如果有空可以按個愛心,做簡報真的有夠累

 

有任何問題歡迎私訊我的 DC:

laiyuchi#3849

\(Reference\)

markdown&Github

By Expect Lai

markdown&Github

基礎但蠻重要的 markdown 跟 Github 介紹

  • 128