Markdown 示例指南

基础语法

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

二级标题

三级标题

四级标题

五级标题

六级标题

*这段文字将是斜体*
_这也将是斜体_

**这段文字将是粗体**
__这也将是粗体__

_你 **可以** 组合它们_

这段文字将是斜体 这也将是斜体

这段文字将是粗体 这也将是粗体

你可以组合它们

列表

无序列表

项目 1
项目 2
- 项目 2a
- 项目 2b

有序列表

项目 1
项目 2
项目 3
1. 项目 3a
2. 项目 3b

图片

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

GitHub Logo

链接

[Hugo](https://gohugo.io)

Hugo

块引用

牛顿曾说：

> 如果我看得更远，那是因为我站在巨人的肩膀上。

如果我看得更远，那是因为我站在巨人的肩膀上。

行内代码

行内 `代码` 有 `反引号` 包围。

行内 代码 有 反引号 包围。

代码块

语法高亮

```go
func main() {
    fmt.Println("Hello World")
}
```

func main() {
    fmt.Println("Hello World")
}

表格

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

Syntax	Description
Header	Title
Paragraph	Text

参考

Markdown 示例

文本样式

样式	语法	示例	输出
粗体	`粗体文本`	`粗体文本`	粗体文本
斜体	`斜体文本`	`斜体文本`	斜体文本
删除线	`~~删除线文本~~`	`~~删除线文本~~`	~~删除线文本~~
下标	`<sub></sub>`	`这是一个<sub>下标</sub>文本`	这是一个_下标文本
上标	`<sup></sup>`	`这是一个<sup>上标</sup>文本`	这是一个^上标文本

引用块

带出处的引用块

不要通过共享内存来通信，而要通过通信来共享内存。
— Rob Pike¹

> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
> — <cite>Rob Pike[^1]</cite>

[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。

提示框

提示框是基于引用块语法的 Markdown 扩展，可用于强调关键信息。支持 GitHub 风格的提示框。请确保您使用的是最新版本的 Hextra 和 Hugo v0.146.0 或更高版本。

[!NOTE] 用户应该知道的有用信息，即使是在浏览内容时。

[!TIP] 帮助用户更好地或更轻松地完成任务的建议。

[!IMPORTANT] 用户需要了解的关键信息，以实现他们的目标。

[!WARNING] 需要用户立即注意的紧急信息，以避免问题。

[!CAUTION] 关于某些操作的风险或负面结果的建议。

> [!NOTE]
> 用户应该知道的有用信息，即使是在浏览内容时。

> [!TIP]
> 帮助用户更好地或更轻松地完成任务的建议。

> [!IMPORTANT]
> 用户需要了解的关键信息，以实现他们的目标。

> [!WARNING]
> 需要用户立即注意的紧急信息，以避免问题。

> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。

表格

表格不是 Markdown 核心规范的一部分，但 Hugo 默认支持它们。

姓名	年龄
Bob	27
Alice	23

|   姓名 | 年龄  |
|--------|------|
|    Bob | 27   |
|  Alice | 23   |

表格中的内联 Markdown

斜体	粗体	代码
斜体	粗体	`代码`

| 斜体   | 粗体     | 代码   |
| --------  | -------- | ------ |
| *斜体* | **粗体** | `代码` |

代码块

{{< cards >}} {{< card link=”../../guide/syntax-highlighting” title=“语法高亮” icon=“sparkles” >}} {{< /cards >}}

列表

有序列表

第一项
第二项
第三项

1. 第一项
2. 第二项
3. 第三项

无序列表

列表项
另一个项
再一个项

* 列表项
* 另一个项
* 再一个项

嵌套列表

水果
- 苹果
- 橙子
- 香蕉
乳制品
- 牛奶
- 奶酪

* 水果
  * 苹果
  * 橙子
  * 香蕉
* 乳制品
  * 牛奶
  * 奶酪

图片

![风景](https://picsum.photos/800/600)

带标题：

![风景](https://picsum.photos/800/600 "Unsplash 风景")

配置

Hugo 使用 Goldmark 进行 Markdown 解析。 Markdown 渲染可以在 hugo.yaml 中的 markup.goldmark 下进行配置。以下是 Hextra 的默认配置：

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    noClasses: false

更多配置选项，请参阅 Hugo 文档中的配置 Markup。

学习资源

进一步阅读

阅读关于操作指南在Diátaxis框架内

在 index.astro 文件中实现重定向到 /zh-cn 有以下几种方法，根据你的需求选择：

方法 1：使用 Astro 的 `redirect()` 函数 (SSR 推荐)

---
// 文件顶部添加
import { redirect } from 'astro:actions';

// 在 GET 请求时重定向
if (Astro.request.method === 'GET') {
  return redirect('/zh-cn', 302);
}
---
<!-- 页面内容不会显示 -->

方法 2：使用 HTML `<meta>` 刷新 (静态站点适用)

---
// 页面逻辑（可选）
---
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0; url=/zh-cn">
  <title>重定向中...</title>
</head>
<body>
  <p>如果页面没有自动跳转，请<a href="/zh-cn">点击这里</a></p>
</body>
</html>

方法 3：使用客户端 JavaScript

---
// 页面逻辑（可选）
---
<html>
<head>
  <script>
    // 客户端重定向
    window.location.href = "/zh-cn";
  </script>
</head>
<body>
  <p>正在跳转到中文版...</p>
</body>
</html>

方法 4：使用 Astro 中间件 (最优雅)

创建 src/middleware.js 文件：

export const onRequest = ({ request }, next) => {
  // 重定向根路径
  if (new URL(request.url).pathname === '/') {
    return new Response(null, {
      status: 302,
      headers: { Location: '/zh-cn' }
    });
  }
  return next();
}

最佳实践建议：

根据部署模式选择：
- SSR 模式：使用方法 1 或方法 4（中间件）
- 静态站点：使用方法 2 或方法 3
SEO 优化：

---
// 添加规范链接防止 SEO 分散
---
<head>
  <link rel="canonical" href="https://yourdomain.com/zh-cn" />
</head>

完整示例（带延迟提示）：

---
// 页面逻辑（可选）
---
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
<meta http-equiv="refresh" content="3; url=/zh-cn" />
  <title>正在跳转到中文版</title>
  <style>
    .redirect-message {
      text-align: center;
      margin-top: 3rem;
      font-family: sans-serif;
    }
  </style>
</head>
<body>
  <div class="redirect-message">
    <h1>正在为您跳转到中文版...</h1>
    <p>如果 3 秒内没有自动跳转，请<a href="/zh-cn">手动点击</a></p>
  </div>

<script>
  setTimeout(() => {
    window.location.href = "/zh-cn";
  }, 3000); // 1.5秒后跳转
</script>
</body>
</html>

重要注意事项：

路径验证：
- 确保 /zh-cn 路由存在
- 对于国际化站点，考虑使用 Astro 官方 i18n 方案：
  Terminal window
```
npm install @astrojs/i18n
```

部署配置：

在 astro.config.mjs 中配置重定向：

import { defineConfig } from 'astro/config';

export default defineConfig({
  redirects: {
    '/': '/zh-cn'
  }
});

性能优化：
- 对于大型站点，建议使用服务端重定向（方法 1 或 4）
- 避免在静态站点中使用客户端重定向（会触发完整页面加载）

选择哪种方法取决于：

你的 Astro 配置（output: 'static' 还是 output: 'server'）
是否需要 SEO 优化
是否已使用国际化中间件

以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的演讲。 ↩

Markdown 示例指南

基础语法

标题

二级标题

三级标题

四级标题

五级标题

六级标题

列表

无序列表

有序列表

图片

链接

块引用

行内代码

代码块

语法高亮

表格

参考

Markdown 示例

文本样式

引用块

提示框

表格

表格中的内联 Markdown

代码块

列表

有序列表

无序列表

嵌套列表

图片

配置

学习资源

进一步阅读

方法 1：使用 Astro 的 redirect() 函数 (SSR 推荐)

方法 2：使用 HTML <meta> 刷新 (静态站点适用)

方法 3：使用客户端 JavaScript

方法 4：使用 Astro 中间件 (最优雅)

最佳实践建议：

重要注意事项：

Footnotes

方法 1：使用 Astro 的 `redirect()` 函数 (SSR 推荐)

方法 2：使用 HTML `<meta>` 刷新 (静态站点适用)