Day13 - Astro Series: Markdown and MDX

Astro 系列文第十三日：Markdown 与 MDX

@ Astro

一个漂亮的渐变背景上面有一句标题：「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，甚至整个网站的布局进行规划。

最后建议实际动手练习：

  • 在 /pages 中创建 Markdown 文件，并熟悉其语法，编写一些文档文章。
  • 在 MDX 中引入已经制作好的组件（可选）

延伸阅读