Astro Markdown 功能测试文章

这是一篇专门用于测试 Astro 博客渲染能力的文章。

本文会覆盖常见 Markdown 元素，包括：

  • 标题与目录
  • 段落
  • 粗体与斜体
  • 图片
  • 表格
  • 引用
  • 有序列表与无序列表
  • 任务列表
  • 行内代码
  • 代码块
  • 链接
  • 分隔线
  • 删除线
  • 嵌套内容

如果你的博客支持自动目录，那么下面这些二级、三级标题应该能够被正确识别。

一、标题与目录测试

这是一个二级标题。

1.1 三级标题

这是三级标题下的正文。

1.1.1 四级标题

这是四级标题。

1.2 另一个三级标题

用于确认目录中多个同级标题是否能够正确显示。

二、文本样式测试

普通正文应该使用博客默认的正文样式。

这是粗体文本。

这是斜体文本。

这是粗体加斜体文本。

这是删除线文本。

这是一个 inline code 行内代码示例。

还可以混合使用，例如：

Astro 的设计理念之一是尽可能减少发送到浏览器的 JavaScript。

三、提示容器测试

提示容器使用引用块语法。第一行写入容器标记；可选标题紧跟在标记后。details 的正文前保留一个空引用行，以分隔 summary 与折叠内容。

查看实现细节

这里是默认折叠的补充内容。它使用原生 details 和 summary，无需客户端 JavaScript。

四、链接测试

普通链接：

Astro 官方网站

自动链接：

https://astro.build/

站内相对链接：

返回首页

也可以测试文章链接：

查看博客列表

四、图片测试

下面是一张普通 Markdown 图片：

示例风景图片

图片下方可以写普通说明文字。

图片测试重点检查：

  • 图片最大宽度
  • 圆角
  • 上下间距
  • 移动端缩放
  • alt 文本
  • 深色模式表现

4.1 宽图测试

宽幅测试图片

4.2 竖图测试

竖版测试图片

五、表格测试

5.1 普通表格

项目 当前方案 推荐方案 状态
框架 Astro Astro ✅
部署 Cloudflare Workers Workers Static Assets ✅
搜索 Pagefind Pagefind ✅
CSS Token + Component CSS 保持 ✅
内容 Markdown Content Collections 🔄

5.2 对齐测试

左对齐 居中 右对齐
Alpha 100 1.25
Beta 200 20.50
Gamma 300 999.99

5.3 长文本表格

功能 说明
Astro Static 在构建阶段生成 HTML，适合博客、个人主页、文档等静态内容站点。
Cloudflare Workers Static Assets 可以直接部署 Astro 生成的 dist 静态资源，同时保留未来扩展 Worker API 的能力。
Pagefind 构建阶段建立搜索索引，无需传统后端搜索服务。

六、引用测试

普通引用：

这是一级引用。

可以包含多行文本。

嵌套引用：

第一层引用

第二层引用

可以用于测试引用块的左边框、背景和缩进。

七、列表测试

7.1 无序列表

  • Astro
  • Cloudflare
  • Pagefind
  • Markdown
  • CSS

7.2 嵌套无序列表

  • Frontend
    • Astro
    • TypeScript
    • CSS
  • Deployment
    • Cloudflare Workers
    • Wrangler
  • Content
    • Markdown
    • RSS
    • Sitemap

7.3 有序列表

  1. 编写 Markdown
  2. 运行 Astro Build
  3. Pagefind 建立索引
  4. Wrangler 上传 dist
  5. Cloudflare 提供静态资源

7.4 嵌套有序列表

  1. 构建项目
    1. Astro 编译
    2. 生成 HTML
    3. 优化静态资源
  2. 构建搜索索引
    1. 扫描 HTML
    2. 生成 Pagefind 数据
  3. 部署网站

7.5 Task List

  • Astro 静态构建
  • Cloudflare Workers 部署
  • Pagefind 搜索
  • 完成文章样式
  • 完成图片样式
  • 完成代码高亮
  • 完成移动端测试

八、代码测试

8.1 JavaScript

const site = {
  name: "pierlee",
  framework: "Astro",
  deployment: "Cloudflare Workers",
};

console.log(site);

8.2 TypeScript

interface Post {
  title: string;
  description: string;
  pubDate: Date;
  tags: string[];
}

const post: Post = {
  title: "Astro Markdown Test",
  description: "Testing Markdown rendering.",
  pubDate: new Date(),
  tags: ["Astro", "Markdown"],
};

8.3 Astro

---
interface Props {
  title: string;
}

const { title } = Astro.props;
---

<article>
  <h1>{title}</h1>
  <slot />
</article>

8.4 CSS

:root {
  --color-background: #ffffff;
  --color-text: #1d1d1f;
  --radius-medium: 0.75rem;
}

article {
  max-width: 48rem;
  margin-inline: auto;
}

8.5 Shell

npm run check
npm run build
npm run preview

8.6 JSON

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build && pagefind --site dist",
    "preview": "npm run build && wrangler dev"
  }
}

九、长段落测试

这一段主要用来测试正文的最大宽度、字号、行高和阅读体验。如果正文内容比较长，那么适当的行宽非常重要。对于中文正文而言，如果内容区域过宽，阅读时视线需要横向移动较长距离；如果过窄，又会导致频繁换行。因此博客正文通常会设置一个适中的 max-width，并通过合理的 line-height 和段落间距来提高长时间阅读时的舒适度。

第二段继续测试段落之间的间距。理想情况下，两个普通段落之间应该存在清晰但不过大的视觉间隔，同时标题与正文、列表、引用、图片之间应该遵循统一的垂直节奏。

十、特殊字符测试

中文标点：

，。！？；：“”‘’（）【】《》

英文标点：

, . ! ? ; : " ' ( ) [ ] { }

特殊字符：

© ™ ® → ← ↑ ↓ × ÷ ± ≠ ≈ ≤ ≥

HTML 特殊字符：

<main>、<article>、<section>、<nav>

十一、混合内容测试

下面测试多个 Markdown 元素连续出现时的布局。

推荐技术栈

  1. Astro

    • 静态优先
    • 默认减少客户端 JavaScript
    • 适合内容型网站

  2. Cloudflare Workers Static Assets

    • 全球 CDN
    • 部署简单
    • 可以未来扩展 Worker API

  3. Pagefind

    • 静态搜索
    • 无需数据库
    • 适合博客

相关命令：

npm run build

构建后生成：

dist/
├── index.html
├── about/
├── blog/
├── posts/
├── pagefind/
├── rss.xml
└── sitemap.xml

如果以上内容都能正确显示，说明你的 Markdown 基础样式已经比较完整。

十二、超长标题测试

这是一个用于测试移动端自动换行、目录显示以及标题行高是否合理的非常非常非常非常长的三级标题

如果这个标题在手机屏幕上仍然能够自然换行，并且不会超出文章容器，就说明响应式标题样式正常。

十三、连续代码与正文测试

下面先出现代码块：

.prose {
  max-width: 48rem;
  margin-inline: auto;
}

然后紧接着正文。

这里主要检查代码块和正文之间是否有足够的上下间距，以及代码块是否会导致整个页面产生横向滚动。

十四、最终检查项

通过这篇文章，可以重点检查：

  • 自动目录是否生成
  • 目录锚点是否正确
  • 滚动定位是否正常
  • 标题层级是否合理
  • 正文宽度是否舒服
  • 图片是否响应式
  • 图片是否溢出
  • 表格是否支持移动端横向滚动
  • 代码块是否横向滚动
  • 代码高亮是否正常
  • 引用样式是否明显
  • 列表缩进是否一致
  • 深色模式是否正常
  • 链接 hover 是否正常
  • focus-visible 是否正常
  • 中文排版是否正常

十五、结语

如果这篇测试文章中的所有元素都能够正确显示，那么你的 Astro 博客基础 Markdown 样式已经覆盖了绝大多数常见文章需求。

后续还可以继续测试：

  • Footnotes
  • Math / KaTeX
  • Mermaid
  • MDX 组件
  • Callout / Admonition
  • 图片 Caption
  • 代码块文件名
  • 代码行高亮
  • Heading Anchor
  • 自动目录滚动高亮

其中这三张图片你需要自己放到 `public/images/`：

```text
public/images/test-cover.jpg
public/images/test-image.jpg
public/images/test-wide.jpg
public/images/test-portrait.jpg

如果只是测试、不想准备四张图片，也可以全部把路径改成同一张：

![测试图片](/images/test-image.jpg)

另外，如果你使用 Astro Content Collections，记得把最上面的 frontmatter 字段改成与你当前 content.config.ts 的 schema 一致，否则文章本身可能因为 schema 校验失败而无法构建。