如何撰寫文章

最後更新：2025年10月25日

歡迎來到星谷雜貨店！這份指南將協助你快速上手發表文章。當然這裡的大部分只是建議，創作的自由仍然在你手上！

開始之前

訪問管理介面

你必須使用具有該儲存庫（Repository）**寫入權限（Write access）**的 GitHub 帳號來登入。目前的編輯器已與 GitHub 完全整合，所有變更將直接推送到儲存庫中。

  • 正式網站登入：直接訪問 https://blog.chinono.com/admin，系統會引導你進行 GitHub 授權。
  • 本地開發環境：運行 npm run dev，然後訪問 http://localhost:3000/admin。

第一步：建立作者資料

在發表第一篇文章前，請先建立你的作者資料！

為什麼要先建立作者？

  • 每篇文章都需要指定作者
  • 作者資料會顯示在文章頁面和側邊欄
  • 有助於讀者了解內容創作者

建立步驟

  1. 點擊左側選單的「作者」(Authors)
  2. 點擊「新增作者」按鈕
  3. 填寫基本資料：
    • 名稱 (必填)：你的顯示名稱
    • 簡介 (必填)：簡短的自我介紹
    • 電子郵件：你的聯絡信箱（選填）
  4. 上傳大頭照：
    • 點擊「上傳圖片」按鈕選擇照片
    • 在裁切視窗中調整範圍
    • 點擊「裁切」按鈕完成
    • 或點擊「從網址新增」直接貼上圖片連結
  5. 新增社群連結（選填）：
    • GitHub：你的 GitHub 個人頁面
    • Twitter：你的 Twitter 帳號連結
    • 個人網站：你的部落格或作品集網址
  6. 預覽與儲存：
    • 右側預覽區會顯示你的作者卡片
    • 確認資料無誤後，點擊右上角的「儲存」

第二步：撰寫第一篇文章

建立新文章

  1. 點擊左側選單的「部落格」(Blog)
  2. 點擊「新增文章」按鈕
  3. 填寫文章資訊

基本資訊

  • 標題 (必填)：文章的主標題
  • 描述 (必填)：文章摘要，會顯示在首頁卡片
  • 發布日期 (必填)：點擊日曆選擇日期

作者與分類

  • 作者 (必填)：從下拉選單選擇你剛建立的作者名稱
  • 標籤 (選填)：新增相關標籤
    • 點擊「新增標籤」
    • 輸入標籤名稱後按 Enter
    • 可新增多個標籤

精選圖片

  • Featured Image (選填)：文章的封面圖片
  • 上傳方式：
    1. 點擊「上傳圖片」選擇檔案
    2. 或點擊「從網址新增」貼上圖片連結
  • 建議尺寸：寬度至少 1200px

撰寫內容

使用 Markdown 格式撰寫文章內容。以下是常用與進階語法：

標題

## 這是 H2 標題
### 這是 H3 標題

標題錨點（自訂 ID）

若要讓目錄或連結能跳到某個標題，可在標題後加上 {#自訂-id}：

### 計算機程式設計 Introduction to Programming {#計算機程式設計}

連結即可用 [計算機程式設計](#計算機程式設計) 跳轉。

段落、換行與列表

這是第一段文字。

這是第二段文字。（段落間空一行）。

如果要在同一段落內換行，請在行尾加上兩個空格再換行，或使用 HTML 標籤 <br>。

- 無序清單項目 1
- 無序清單項目 2

1. 有序清單項目 1
2. 有序清單項目 2

粗體與斜體

**粗體文字**
*斜體文字*
***粗斜體***

連結與圖片

[連結文字](https://網址)
![圖片描述](圖片網址)

帶說明文字的圖片（Figure + Caption）：在網址後加上空格和標題（用引號包圍）即可：

![圖 1](圖片網址 "這是圖說文字")

彩色標籤與文字底色

可用簡化語法 [文字]{.類別} 顯示特定顏色或樣式，常用於標籤或螢光筆效果：

  • 顏色標籤：.red-1 到 .red-5（支援紅、橘、黃、綠、青、藍、紫、粉紅、灰各五種深淺，例如 .red-3, .green-2），也支援舊版 .red, .green 等。
必修課
選修課
  • 文字底色（背景色）：.bg-red-1 到 .bg-red-5
這段重要文字背景會亮起來
  • 底線與螢光筆：
畫底線的文字
黃色螢光筆

資訊框（Callout blocks）

可用來顯示提示、警告等訊息，也可直接從編輯器的「+」按鈕插入。

:::info
這是一段**提示**訊息。
:::

:::warning
這是一段**警告**訊息！
:::

:::success
這是一段**成功**訊息。
:::

:::error
這是一段**錯誤**訊息。
:::

可折疊的資訊框（補充説明）

當資訊框的第一行是一個標題（例如 ### 補充説明：...）時，該資訊框在網站上會自動變成可折疊（collapsible）。讀者預設只會看到標題，點擊標題才會展開完整內容。

這很適合用來放「進階解釋」、「補充説明」、「延伸閱讀」等長篇段落——既能保留內容深度，又不會打斷主線閱讀節奏。短的資訊框（沒有標題開頭的）則維持原本展開的樣子。

:::info
### 補充説明：什麽是 IID？

我們把這個詞拆成兩半來看：「獨立」和「同分布」...
（這裡可以寫很多段落，讀者預設看不到，點開才會顯示。）
:::

要讓資訊框保持原樣（一直展開），只要不要用標題當作第一行即可。

引用與程式碼

> 這是一段引用文字

行內程式碼：

使用 `console.log('Hello')` 輸出訊息

程式碼區塊：

```javascript
function hello() {
  console.log('Hello, World!');
}
```

使用編輯器快捷元件

點擊編輯器上方的「+」按鈕，可插入特殊元件：

  • 資訊框：顯示提示、警告等訊息
  • YouTube 影片：嵌入 YouTube 影片
  • 程式碼區塊：帶語法高亮的程式碼
  • 圖片說明：帶說明文字的圖片
  • 引用框：引用樣式

預覽與發布

預覽文章

  • 右側預覽區會即時顯示文章樣式
  • 上方顯示「文章卡片預覽」（首頁顯示效果）
  • 下方顯示完整文章內容預覽

儲存與發布文章

在新的編輯器中，文章有「草稿」與「發布」兩種狀態：

  1. 儲存草稿：點擊右上角的「儲存草稿」，修改會存至儲存庫中的 draft 資料夾。
  2. 發布變更：點擊「發布變更」，文章會正式移至 blog 資料夾，並自動推送到 GitHub 發布。
  3. 如果你想撤銷修改，可點擊「還原 GitHub 版本」。

文章撰寫最佳實踐

標題建議

  • H1 (#)：不要使用，文章標題欄位已是 H1
  • H2 (##)：用於主要章節
  • H3 (###)：用於次要章節

圖片建議

  • 使用高品質圖片（至少 1200px 寬）
  • 為圖片添加描述（alt text）
  • 實在找不到圖片可以考慮使用免費圖庫：Unsplash、Pexels

標籤建議

  • 使用 1-3 個相關標籤
  • 保持標籤簡潔（2-3 字）

內容建議

  • 段落不要太長（3-5 行為佳）
  • 適時使用標題分隔內容
  • 加入圖片或程式碼範例增加可讀性
  • 確認連結都能正常開啟

編輯現有文章

  1. 點擊「部落格」進入文章列表
  2. 點擊要編輯的文章
  3. 修改內容
  4. 點擊右上角的「發布變更」或「儲存草稿」將改動直接同步至 GitHub

常見問題

為什麼看不到我的文章？

確認你已經點擊「發布變更」而不是只有「儲存草稿」。等待幾分鐘讓網站重新部署。

可以刪除文章嗎？

可以。你必須先將發布的文章點擊「取消發布」退回草稿狀態，接著才會出現「刪除草稿」按鈕，點擊後即可刪除。

圖片上傳失敗怎麼辦？

  • 檢查圖片大小（建議小於 5MB）
  • 使用常見格式（JPG、PNG）
  • 或使用「從網址新增」功能

如何更改作者資料？

點擊「作者」選單，選擇你的作者資料，修改後點擊「儲存」即可。

標籤可以重複使用嗎？

可以！建議重複使用相同標籤，方便讀者按標籤瀏覽文章。

預覽和實際網站不一樣？

預覽僅供參考，某些樣式只會在實際網站上顯示。

祝你寫作愉快！