Markdown 局部布局：分栏与时间线

@navfolio/plugin-markdown 现在内置局部布局指令。它们只改变文章正文中某一段内容的排列方式，不会影响博客页面、侧栏或主题的整体布局。

目前提供两种布局：通用 columns 分栏，以及按时间顺序阅读的 timeline。列、时间线事件内继续使用普通 Markdown，因此标题、图片、加粗、链接、引用和列表都照常可用。

启用

布局能力默认开启；在 navfolio.config.ts 中显式声明时，配置如下：

1
import { markdownPlugin } from '@navfolio/plugin-markdown';
2

3
export default defineNavfolioConfig({
4
  plugins: [
5
    markdownPlugin({
6
      layouts: true,
7
    }),
8
  ],
9
});

默认主题已经包含布局样式。使用自定义主题时，导入 @navfolio/plugin-markdown-layouts/styles.css，并根据 .markdown-columns 和 .markdown-timeline 等类名覆盖视觉样式。

分栏

一个分栏由 columns 容器和若干 column 组成。开始、结束与每一列的指令行都要单独占一段。

1
::: columns{cols=2 ratio=1:2}
2

3
::: column
4

5
左侧内容。
6

7
:::
8

9
::: column
10

11
右侧内容。
12

13
:::
14

15
:::

cols 可以省略，渲染器会根据 column 数量推断。若显式填写，它必须与实际列数一致。ratio 用冒号分隔正数来控制宽度比例；不填写时每列等宽。

媒体列

媒体不是另一种布局，而是带有 media 标记的一列。显式标记避免把普通截图误判为媒体内容。下例在宽屏时让文字与图片并排，在窄屏时则把图片移到文字前面。

1
::: columns{cols=2 ratio=3:2 mobile=media-first}
2

3
::: column
4

5
文字内容。
6

7
:::
8

9
::: column{media}
10

11
![图片说明](/src/assets/figure/blog-sample-picture.png)
12

13
:::
14

15
:::

mobile=media-first 仅在标记了 media 的列存在时生效；不设置它时，窄屏堆叠保持 Markdown 的原始顺序。

时间线

timeline 包含按顺序排列的 event。每个事件的 date 用作可读的日期标签，事件正文可以包含标题、段落或列表。

1
::: timeline
2

3
::: event{date=2024.06}
4

5
### 收集
6

7
整理零散素材。
8

9
:::
10

11
::: event{date=2025.01}
12

13
### 发布
14

15
发布第一个版本。
16

17
:::
18

19
:::

横向时间线

当节点较少且连续时，可以显式使用横向时间线。事件列不会为适应窄屏而压缩；超出正文宽度时会出现横向滚动条，保留时间顺序与每个节点的可读宽度。

1
::: timeline{direction=horizontal}
2

3
::: event{date=2024.06}
4

5
### 收集
6

7
:::
8

9
::: event{date=2024.10}
10

11
### 成形
12

13
:::
14

15
::: event{date=2025.01}
16

17
### 发布
18

19
:::
20

21
:::

响应式行为

• columns 在 720px 以下变为单列，并保留每列内的原生 Markdown。
• 使用 mobile=media-first 的媒体列在窄屏时优先出现。
• 纵向时间线在所有尺寸保持纵向，日期与事件内容仍然对齐。
• 横向时间线始终横向排列；桌面与手机都可以使用原生横向滚动查看完整节点。

同类布局不能嵌套在 column 或 event 内。结构不完整、列数不匹配或比例数量不匹配的指令会原样显示，以避免渲染器吞掉作者内容。