iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 26
1
Software Development

你會十五種程式語言?不,我會十五種HelloWorld.為了避免這種狀況,因此寫了這篇:淺入淺出十五種程式語言系列 第 26

附錄1. Markdown 工程師們的共同語言

Markdown

十五種語言都介紹完了,後面我們就當作附錄來介紹一些工程師們的基本能力吧
以下是第一篇

寫在前面

Markdown並不能算是程式語言,而是標記式語言
程式語言必須有基本的邏輯運算能力
而Markdown提供的並不是運算能力,而是讓你用一些特殊的標記在寫的文字上,
讓原本的文字在特定的轉換下可以產生特殊的效果

那為什麼說他是工程師們的共同語言呢?

理由在於github之類的網站都預設可以讓你使用Markdown的語法來發文
比方說專案的ReadME

點擊文章部份右上角的Raw

https://ithelp.ithome.com.tw/upload/images/20200926/20127836wKInho35Jy.png

然後你應該會看到這篇文章原始的樣子
https://ithelp.ithome.com.tw/upload/images/20200926/20127836sxQCG6PXLr.png

Markdown就是這麼神奇,可以將原本的文字依照少少的幾種標記,就產生相當好看的頁面

就連IT邦的發文也是按照這種格式喔

Markdown語法

先去幫VScode安裝Markdown的插件吧
直接挑最多人下載的那個

https://ithelp.ithome.com.tw/upload/images/20200926/201278369uvp0Qw07d.png

標題

先從標題開始吧,開一個新的專案目錄,然後建立一個附檔名為.md的檔案,然後貼上

# 標題

## 次級標題

### 三級標題

#### 四級標題

##### 五級標題

###### 六集標題

接著點擊上方的預覽按鈕,你就可以看到VScode將你的Markdown轉成文件的樣子

https://ithelp.ithome.com.tw/upload/images/20200926/20127836F2klzMmwTD.png

標題的寫法是在前面加上不同數量的#以及一格空格
注意空格在Markdown中相當重要,每個標記後面都要加上一個空格,如此Markdown才知道這段是需要轉換的文字
你可以嘗試將其中一個標題的空格拿掉試試會發生什麼事

標題總共有六級
一級標題下方會有特殊的分隔線

清單

清單的長相如下

  • 清單1
  • 清單2
  • 清單3

Markdown的標記方式有好幾種

- 清單1
- 清單2
- 清單3

+ 清單1
+ 清單2
+ 清單3

* 清單1
* 清單2
* 清單3

如果你需要有序清單,也可以這樣寫

1. 清單1
2. 清單2
3. 清單3

甚至可以使用次級清單

- 清單1
  + 次級清單1-1
    - 次次級清單
  - 次級清單1-2
* 清單2
  - 次級清單2-1

標記方式都可以混用

如果你需要大段落的清單,當然也是沒問題

- 清單第1行  
  清單第2行
  清單第3行
  清單第4行
  清單第5行
- 清單項目2

記得喔,如果你需要分行,那麼也需要標記,一般的Enter並不會讓Markdown轉成換行符
而是需要在行尾加上兩個空格
你可以嘗試看看如果把行尾的空格拿掉會發生什麼事

引言

這個就是引言

引言的目的是將特殊的文字段落給標記出來
在傳統的e-mail用法是回覆特定訊息時用來摘錄原句

標記方式如下

> 引言

如果你需要,也是可以多級引言

一級引言

次級引言

三級引言

寫法如下

> 一級引言
> > 次級引言
> > > 三級引言

分隔線

有時候你會需要分隔線來確保段落的完整性


標記方式是三個或以上的如下符號

---
***
___

第三種是下底線_

表格

此行置左 此行置中 此行置右
1-1 2-1 3-1
1-2 2-2 3-2
1-3 2-3 3-3

在Markdown中生產表格的方式比較麻煩

| 此行置左 | 此行置中 | 此行置右 |
| -------- | :------: | -------: |
| 1-1      |   2-1    |      3-1 |
| 1-2      |   2-2    |      3-2 |
| 1-3      |   2-3    |      3-3 |

表格的語法上可以通融的部份較多,這裡不一一介紹
如果你懶得打那麼多字,也可以選擇一些表格的線上產生工具

超連結

在你寫一些文件的過程中,難免會需要超連結的語法
鐵人賽

寫法如下

[鐵人賽](https://ithelp.ithome.com.tw/articles/10233518)

[這裡是你要在頁面上顯示的文字](這裡則是網址)

插入圖片

與超連結類似的是插入圖片

圖片

語法如下

![圖片](https://ithelp.ithome.com.tw/storage/image/logo.svg)

![這裡放的是將滑鼠移上圖片後要顯示的文字](這裡則放圖片的連結)  

跟超連結的差別是前面要加上!
如果你是要單機使用的Markdown,連結內也可以放你本地的圖片路徑

程式碼區塊

看到這裡你有沒有覺得為什麼我偶爾打出來的字會自動轉換形式,偶爾不會
理由在於我使用了

程式碼區塊

長這樣

```
程式碼區塊
```

只要是要顯示的語法我都會放在程式區塊內,這樣他就會按照原本的樣子顯示
這區塊的用途主要是用來顯示程式碼的語法,讓Markdown自動去高亮
比方說你可以這樣寫

```go
程式碼區塊
```

就會變成這樣

func main(){
    a := 12
    fmt.Println(a)
}

他會根據你標注的程式語言名稱去高亮你的程式碼

強調

Markdown也有強調的標記

方法是使用

*斜體字*

_斜體字_

**粗體字**

__粗體字__

~~刪除線~~

混用

這些語法都是可以混用的喔
你可以這樣寫

  • 清單1
    • 這是重點
    • 這是斜體
  • 已完成清單
  • 引言內的 強調

coulmn column
第一欄
第二欄

你可以自己去組合自己喜歡的樣式

那麼,該如何使用呢?

如果你將要成為一個工程師,那麼就一定會需要撰寫文件
畢竟除非你是個人工作室,否則你的程式碼終究是要給別人看的

我們來看看台灣第一程式設計師唐鳳怎麼寫專案的README的吧
看不懂沒關係,我們沒必要跟天才一樣寫出這麼複雜的文件

這個就相對來說比較簡單
你可以參考她的寫法來解釋自己的程式該如何使用

或是如同水土保持生產履歷的開源專案一樣
單純寫一份專案文檔

如何寫文檔是一門學問

有些公司會有規範,或是你會有自己的一套哲學

當你的程式會有更新,不管是修正bug或是新增功能
這時你就需要寫更新文檔,讓使用者知道什麼bug被修復或是可以使用什麼新功能

如果你遊玩遊戲的話可以參考遊戲的更新檔說明
看看要怎麼寫會比較吸引你的注意


上一篇
語言的比較
下一篇
附錄2. 參考與指標 Reference, or not reference: that is the question
系列文
你會十五種程式語言?不,我會十五種HelloWorld.為了避免這種狀況,因此寫了這篇:淺入淺出十五種程式語言30

尚未有邦友留言

立即登入留言