Day13 - Astro Series: Markdown and MDX

Astro 系列文第十三日:Markdown 與 MDX

一個漂亮的漸層背景上面有一句標題:「Markdown 與 MDX」

前言

前面介紹了元件與路由,相信製作靜態為主的網站已經難不倒你,甚至還可以發揮 Astro 最強大的優勢,透過選擇性 Hydration 添加些動態內容到頁面之中。

但撰寫網站最終還是要回歸到易於維護,能不能不需要接觸程式,只需透過編寫文件就能更改頁面內容呢?也就是將內容與版面、邏輯做分離。

本章節我們將會學習 Markdown 與 MDX 來達成這件事。

Markdown

Markdown 懶人包

Markdown🔗 是輕量級的標記語言,甚至你會在一些論壇或是筆記軟體中接觸到這款語言用於編寫文件。可以在 src/pages 創建 .md 文件並且用它來編寫你的網頁。

除了編寫網頁文件,也可以在檔案的開頭添加 YAML 格式的 Frontmatter,將一些文件額外的資料給記錄下來,像是:標題、作者、日期、分類……等

---
title: 我的第一個 Markdown 檔案
author: 'Joe'
publishDate: '2023'
category: 'other'
---
# 這是我的第一個 Markdown 檔案
可以透過 Markdown 文件來添加一些基礎的語意,像是:
- **粗體**_斜體_
- [連結](https://astro.build)
- ![圖片](image.jpg)
- ……更多

撰寫 Markdown 相較於 HTML 更為輕便而且不用煩惱過多的細節,並且保留極高的靈活度。

MDX

左邊是一段 MDX 代碼,右邊是一個由 MDX 產生的畫面

可以額外透過安裝 MDX 整合🔗來讓 Astro 支援 MDX。MDX🔗 就像 Markdown 與 JSX 的綜合體,單純的 Markdown 可能無法滿足你撰寫複雜文章的需求,像是添加額外的元件或動態資料,這時候 MDX 就是很好的選擇。舉例來說我的部落格文章有示範 React 元件的需要,因此就是很好的時機使用 MDX。

在 MDX 使用導出的變數與 Frontmatter

可以透過 {JSX 表達式} 來呈現變數內容,也可以存取 Frontmatter 的內容。

export const title = '我的 MDX 變數';
# {title}
---
subHeadline: '我的第一篇 MDX 文章'
---
# {frontmatter.title}

在 MDX 使用元件

可以在 MDX 元件中引入 Astro 元件或者是其他 UI 框架的元件,用法和在 .astro 的情況一樣!

---
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';
以下按鈕是一個 Astro 元件,在 MDX 中被引入:
<Button title="Contact me" />.
以下是我的計數器元件,在 MDX 中被引入:
<ReactCounter client:load />

其他特性

標題 ID

使用標題將會自動生成 ID,好讓你使用 <a> 連結通往文件中的某個區塊。

## 前言
這裡是前言,想直接按結論可以到 [總結區塊](#總結)
## 內容
...
## 總結
...

特殊字元

一些特殊的字元將會被解讀為 HTML 或 JavaScript 的代碼,像是 <{,因此建議使用HTML 字符實體🔗來替代,像是 &lt; 或是 &lcub;

語法高光

預設 Astro 支援使用 Shiki🔗Prism🔗 來為代碼提供語法高光,可以透過以下幾種方式來顯示:

  • 在 Markdown 或 MDX 中使用代碼圍欄(`````)
  • 使用內建 <Code/>🔗 元件
  • 使用內建 <Prism />🔗 元件

預設將會使用 Shiki ,並且採用 github-dark 樣式,所有的樣式都會採用行內注入,不會有額外的樣式檔、客戶端 JavaScript 需要處理。進一步的設定可以在章節四中了解。

額外插件

Astro 使用 remark 來處理 Markdown 並且預設應用了 GitHub 風格的 Markdown🔗SmartyPants🔗 插件。更多插件的設置細節可以在第四章節 - 基礎指令與設定中的 Markdown 設定🔗中設置。

總結

先對這兩種檔案格式有個印象,下一章節將會介紹如何替這些 .md.mdx 甚至是整個網站的布局進行規劃。

最後會建議實際動手練習:

  • 創建 Markdown 檔案在 /pages 當中,並且熟悉其語法,編寫一些文件文章。
  • 在 MDX 中引入製作好的元件(可選)

延伸閱讀